Configuring JNDI Component interface/implementation mapping

In Brief

Following things must be done in order to successfully plugin component implementation:

• The MetaBossComponentNamingProvider.jar must be included in the classpath. This jar contains the special MetaBoss 'component:/' JNDI URL context resolver.
• The jar containing the desired component implementation must be present on the classpath or, alternatively, anywhere in the subdirectory of any directory listed in com.metaboss.naming.component.ComponentImplPath.

• The JNDI component mapping property must be set in the jndi.properties file. This mapping is used to find an implementation class for the component being looked up. Each mapping property is a key-value pair where key is used to identify one or more COMPONENT_URLs this mapping property is applicable to and value is used to locate the object factory used to obtain the implementation of the component. The formal syntax of the mapping key is:

  com.metaboss.naming.component.<Interface Package>[.<Interface Name>][/<Caller Identifier>]

  where:

  • com.metaboss.naming.component. is the constant prefix which sets apart MetaBoss JNDI properties from others.
  • <Interface Package> is the mandatory name of the Java package of the Component Interface. The name may contain '*' and '**' wildcards (see additional notes below on how wildcards are used)
  • <Interface Name> is the optional name of the Java interface of the Component Interface. The name may contain '*' and '**' wildcards (see additional notes below on how wildcards are used). If name is not given - all Components whose interfaces are located in the matching package will match this mapping key.
  • <Caller Identifier> is the optional identifier of the client who is doing lookup. The caller is identified by package, class and method name of the location where the lookup call is made from. The formal syntax of the caller identifier is:
    
    <Package Name>[.<Class Name>[.<Method Name>]]
    
    The caller identifier may contain '*' and '**' wildcards (see additional notes below on how wildcards are used). If caller identifier is not given - all callers other than the ones individually mapped will match this mapping key.

  The mapping value contains the name of the package where object factory for the component implementation can be located. A small number of special macros can be used to specify special values derived from the mapping key. This is primarily used when the mapping key contains wildcards and we need to use the whole or portion of the actual name known only at the run-time. Supported keywords are:
  
  

  • ${component} this keyword will be replaced by the full name of the component (package name plus interface name).
  • ${componentName} this keyword will be replaced by the name of the component interface.
  • ${componentPackage} this keyword will be replaced by the name of the component package.
  • ${client} this keyword will be replaced by the full name of the client (package name plus class name).
  • ${clientName} this keyword will be replaced by the name of the client class.
  • ${clientPackage} this keyword will be replaced by the name of the client package.

Some examples

#
# This example shows a fragment of jndi.properties file with various component
# implementation mapping instructions.
#

#
# Map somepackage.SomeComponent component for cases when it is called
# from the location inside clientpackage package
#
com.metaboss.naming.component.somepackage.SomeComponent/clientpackage=somepackage.someimpl

#
# Map all components from somepackage package for cases when they are called
# from the location inside clientpackage.clientclass.clientmethod
#
com.metaboss.naming.component.somepackage/clientpackage.clientclass.clientmethod=somepackage.someimpl

#
# Map somepackage.SomeComponent component for cases when it is called
# from any location for which there is no explicit mapping
#
com.metaboss.naming.component.somepackage.SomeComponent=somepackage.someimpl

#
# Map all components from somepackage package for cases when they are called
# from any location for which there is no explicit mapping
#
com.metaboss.naming.component.somepackage=somepackage.someimpl

#
# Map all storage components to the oracle implementation subpackage
#
com.metaboss.naming.component.**.storage=${componentPackage}.oracleimpl

Location of the mapping properties

This area is under construction

Additional Notes

Component Name and Package values can be found in the jndi lookup string. MetaBoss generators usually generate the public final static String COMPONENT_URL constant into the component interface class. This constant must be used as a lookup string. This string always starts from the "component:/" prefix. The prefix is used by JNDI to find and invoke the appropriate context resolver. Following the prefix this string contains the full component name, which includes the package name and component name in java class naming style (i.e. dot separated). This is sometimes followed by the component version expression in form "/<major version no>.<minor version no>"

The widcard characters '*' and '**' can be used in the mapping key to create generic mapping rules covering families of components. They work very similar to the Apache Ant file name patterns. The '*' wildcard will match any number of characters excluding '.' - so it does not cross the package level. The '**' wildcard will match any number of characters including '.' - so it is able to cross the package level. Note also that the '/' character separating component interface definition from optional caller identifier can not be substituted by any wildcard, so it always must be present if caller identifier is present.

When mapping key matching process takes place the more explicit maping keys will be attempted earlier than the least explicit ones.

The Implementation package stated in the mapping must contain a naming factory class, which implements the javax.naming.spi.ObjectFactory interface. The name of this factory class is expected to be <ComponentName>Factory. For example, for component named 'SomeComponent' the expected factory class name is 'SomeComponentFactory'.