NamingConventionClassEnquirer
Date: 2015-08-04

jep

## Class NamingConventionClassEnquirer

- java.lang.Object
- - jep.NamingConventionClassEnquirer

- All Implemented Interfaces:
    ClassEnquirer

      public class NamingConventionClassEnquirer
      extends java.lang.Object
      implements ClassEnquirer

  A simple `ClassEnquirer` to see if the package/class to be imported in a Python sub-interpreter should be considered as a Java package/class. This enquirer can check for import statements beginning with java, com, gov, etc and country codes such as us, uk, fr, ch, etc.

  This class is useful for the following scenarios:

  - You don't want the overhead of initializing `ClassList.getInstance()`
  - You don't want all the classes in a package automatically imported
  - You don't have Python modules that resemble Java package names

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `protected java.util.Set<java.lang.String>` | `javaNames`
    `protected static java.util.List<java.lang.String>` | `TOP_LEVEL` the default top level package names: java, javax, com, gov, org, edu, mil, net

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `NamingConventionClassEnquirer()` Convenience constructor.
    `NamingConventionClassEnquirer(boolean includeDefaults)` Constructor
    `NamingConventionClassEnquirer(boolean includeDefaults, boolean includeCountryCodes)` Constructor

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `addTopLevelPackageName(java.lang.String pkgStart)` Adds a top level package name to the list of names that should be considered as Java packages
    `boolean` | `contains(java.lang.String name)` Checks if the name is likely available in Java.
    `java.lang.String[]` | `getClassNames(java.lang.String pkgName)` Given a Java package name, gets the fully-qualified classnames available for import in the package.
    `boolean` | `supportsPackageImport()` Whether or not this ClassEnquirer supports importing Java classes at the package level in addition to the class level.

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Field Detail

    - #### TOP_LEVEL

          protected static final java.util.List<java.lang.String> TOP_LEVEL

      the default top level package names: java, javax, com, gov, org, edu, mil, net

    - #### javaNames

          protected java.util.Set<java.lang.String> javaNames

  - ### Constructor Detail

    - #### NamingConventionClassEnquirer

          public NamingConventionClassEnquirer()

      Convenience constructor. Includes defaults but not country codes.

    - #### NamingConventionClassEnquirer

          public NamingConventionClassEnquirer(boolean includeDefaults)

      Constructor
      Parameters:
        `includeDefaults` - whether or not typical package names such as java, javax, com, gov should be considered as a java package.

    - #### NamingConventionClassEnquirer

          public NamingConventionClassEnquirer(boolean includeDefaults,
                                       boolean includeCountryCodes)

      Constructor
      Parameters:
        `includeDefaults` - whether or not typical package names such as java, javax, com, gov should be considered as a java package.
        `includeCountryCodes` - whether or not a name starting with a 2-letter country code such a uk, de, fr, us, ch should be considered as a Java package.

  - ### Method Detail

    - #### addTopLevelPackageName

          public void addTopLevelPackageName(java.lang.String pkgStart)

      Adds a top level package name to the list of names that should be considered as Java packages
      Parameters:
        `pkgStart` - the start of a java package name to check, e.g. com, gov, us, it, fr

    - #### contains

          public boolean contains(java.lang.String name)

      Description copied from interface: `ClassEnquirer`
      Checks if the name is likely available in Java. A return value of true implies the name corresponds to a Java package or class, but does not guarantee that an import will succeed. A return value of false implies that an import from Java would fail, but does not guarantee that an import will fail.
      Specified by:
        `contains` in interface `ClassEnquirer`
      Parameters:
        `name` - the name to check, such as java, java.util, java.util.ArrayList
      Returns:
        true if it's likely supported by Java, false if it's likely python

    - #### supportsPackageImport

          public boolean supportsPackageImport()

      Description copied from interface: `ClassEnquirer`
      Whether or not this ClassEnquirer supports importing Java classes at the package level in addition to the class level. For example, with the right ClassLoader Jep should always be able to successfully import Java classes with syntax such as:

           from java.util import ArrayList
           o = ArrayList()

      However, only in some scenarios can the package be imported separately without the fully qualified name, such as:

           import java.util as ju
           dir(ju)
           o = ju.ArrayList()

      This also roughly corresponds to whether or not `dir(javaPackage)` will return a list of available classes or only the classes that have been explicitly imported.
      Specified by:
        `supportsPackageImport` in interface `ClassEnquirer`
      Returns:
        true if this ClassEnquirer supports import of packages in addition to import of classes, false if it only supports importing classes.

    - #### getClassNames

          public java.lang.String[] getClassNames(java.lang.String pkgName)

      Description copied from interface: `ClassEnquirer`
      Given a Java package name, gets the fully-qualified classnames available for import in the package. In general this method should return null if `ClassEnquirer.supportsPackageImport()` returns false.
      Specified by:
        `getClassNames` in interface `ClassEnquirer`
      Parameters:
        `pkgName` - the name of a package the ClassEnquirer supports, such as java.util
      Returns:
        the list of classnames in the package