jfun.yan.xml
Class NutsProcessor

java.lang.Object
  jfun.yan.xml.NutsProcessor

All Implemented Interfaces:

java.io.Serializable

public class NutsProcessor
extends java.lang.Object
implements java.io.Serializable

The main class that parses an xml config file and populates container and lifecycle manager with the information stored in the config file.

Author:

Ben Yu

See Also:

Serialized Form

Constructor Summary

NutsProcessor()
Create a NutsProcessor object.

NutsProcessor(java.lang.ClassLoader classloader)
Create an NutsProcessor object.

NutsProcessor(java.lang.ClassLoader cloader, Container yan)
Create an NutsProcessor object.

NutsProcessor(java.lang.ClassLoader cloader, Container yan, DefaultLifecycleManager manager, java.io.File basedir)
Create an NutsProcessor object.

NutsProcessor(java.lang.ClassLoader classloader, ResourceLoader rloader)
Create an NutsProcessor object.

NutsProcessor(java.lang.ClassLoader cloader, ResourceLoader rloader, Container yan)
Create an NutsProcessor object.

NutsProcessor(java.lang.ClassLoader cloader, ResourceLoader rloader, Container yan, DefaultLifecycleManager manager, java.io.File basedir)
Create an NutsProcessor object.

Method Summary

NutsProcessor	createMetaInterpreter() Create an NutsProcessor object that's gonna be used to load meta configuration of Nut classes.
NutsProcessor	createMetaProcessor(java.lang.ClassLoader loader) Create an NutsProcessor object that's gonna be used to load meta configuration of Nut classes.
NutsProcessor	createMetaProcessor(java.lang.ClassLoader loader, ResourceLoader rloader) Create an NutsProcessor object that's gonna be used to load meta configuration of Nut classes.
java.lang.Object	deserialize(java.lang.Class type, java.lang.String v) Convert a string literal to an object of a certain type.
NutDescriptor	findNut(java.lang.String key) Get a NutDescriptor registered by putNut().
java.lang.Object	findService(java.lang.Object key) To find the service object registered using registerService(Object, Object).
java.io.File	getBaseDir() To get the base directory used by the processor.
java.lang.ClassLoader	getClassLoader() To get the ClassLoader used to load component classes.
Container	getContainer() To get the container used by this processor.
DefaultLifecycleManager	getLifecycleManager() To get the lifecycle manager used by this processor.
java.util.Set	getNutKeys() Get the set of keys of Nut descriptors.
ParameterBinder	getParameterWiring() Get the default parameter auto wiring mode.
PropertyBinder	getPropertyWiring() Get the default property auto-wiring mode.
ResourceLoader	getResourceLoader() To get the ResourceLoader used to load resources.
java.util.Set	getServiceKeys() Get the set of the keys of the service objects.
SingletonMode	getSingletonMode() Get the default singleton mode.
java.lang.Object	getVariable(java.lang.String key) To get a variable value.
boolean	hasVariable(java.lang.String key) Checks whether a variable name exists.
boolean	isDeserializable(java.lang.Class type) To determine if string literal can be converted to the target type.
void	loadNutsFromContainer(Container nuts) Load descriptors of the nut classes registered in a Container.
void	loadNutsMetaData(java.lang.Object id, java.lang.ClassLoader loader, ResourceLoader rloader, java.io.InputStream in) Load configuration information from an InputStream and wires Nut classes.
void	loadNutsMetaData(java.lang.Object id, java.io.InputStream in) Load configuration information from an InputStream and wires Nut classes.
void	loadNutsMetaFile(java.lang.ClassLoader loader, ResourceLoader rloader, java.lang.String filename) Load a configuration file that wires Nut classes.
void	loadNutsMetaFile(java.lang.String filename) Load a configuration file that wires Nut classes.
void	loadNutsMetaResource(java.lang.String resourcename) Load configuration information from a resource loaded by the component class loader.
java.util.Map	preInstantiate() Pre-initialize eagerly instantiated components.
java.util.Map	preInstantiate(Container container) Pre-initialize eagerly instantiated components.
java.util.Map	preInstantiate(Container container, java.util.Map store) Pre-initialize eagerly instantiated components.
java.util.Map	preInstantiate(java.util.Map store) Pre-initialize eagerly instantiated components.
java.lang.String[]	process(java.lang.Object id, java.io.InputStream in) Process bytes read from an InputStream.
java.lang.String[]	processFile(java.io.File file) Process a config file.
java.lang.String[]	processFile(java.lang.String filename) Process a config file.
java.lang.String[]	processResource(java.lang.String resourcename) Process a resource from the component class loader as an xml configuration.
void	registerAutoWiring(java.lang.String mode_name, ParameterBinder mode) Register a parameter autowiring mode.
void	registerAutoWiring(java.lang.String mode_name, PropertyBinder mode) Register a property autowiring mode.
void	registerDeserializer(java.lang.Class type, Deserializer deserializer, boolean overriding, boolean mandatory) To register a Deserializer.
void	registerNut(java.lang.String key, NutDescriptor desc) Add an external nut descriptor for the processor to use.
void	registerService(java.lang.Object key, java.lang.Object service) To register a service object that can be read by customized Nuts classes through the call of NutEnvironment.findService(Object).
void	registerVariable(java.lang.String key, java.lang.Object val) Register a variable that can be referenced in the xml file using "$varname" syntax.
void	removeNut(java.lang.String key) Unregister a NutDescriptor.
void	removeVariable(java.lang.String key) To remove a registration of a variable.
void	setParameterWiring(ParameterBinder param_wiring) Set the default parameter auto-wiring mode.
void	setPropertyWiring(PropertyBinder prop_wiring) Set the default property auto-wiring mode.
void	setSingletonMode(SingletonMode singleton_mode) Set the default singleton mode.
void	unregisterService(java.lang.Object key) To unregister a service object.

Methods inherited from class java.lang.Object

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

Constructor Detail

NutsProcessor

public NutsProcessor()

Create a NutsProcessor object.

The ClassLoader object that loads this class is used to load the nut classes and the component classes.

NutsProcessor

public NutsProcessor(java.lang.ClassLoader classloader)

Create an NutsProcessor object.

Parameters:

classloader - the ClassLoader object to load component classes and resources.

NutsProcessor

public NutsProcessor(java.lang.ClassLoader classloader,
                     ResourceLoader rloader)

Create an NutsProcessor object.

Parameters:

classloader - the ClassLoader object to load component classes.

rloader - the ResourceLoader object to load resources.

NutsProcessor

public NutsProcessor(java.lang.ClassLoader cloader,
                     Container yan,
                     DefaultLifecycleManager manager,
                     java.io.File basedir)

Create an NutsProcessor object.

Parameters:

cloader - the ClassLoader object to load component classes and resources.

yan - the container that registers the components.

manager - the life cycle manager.

basedir - the base directory against which relative paths found in the config file can be resolved.

NutsProcessor

public NutsProcessor(java.lang.ClassLoader cloader,
                     ResourceLoader rloader,
                     Container yan,
                     DefaultLifecycleManager manager,
                     java.io.File basedir)

Create an NutsProcessor object.

Parameters:

cloader - the ClassLoader object to load component classes.

rloader - the ResourceLoader object to load resources.

yan - the container that registers the components.

manager - the life cycle manager.

basedir - the base directory against which relative paths found in the config file can be resolved.

NutsProcessor

public NutsProcessor(java.lang.ClassLoader cloader,
                     Container yan)

Create an NutsProcessor object.

Parameters:

cloader - the ClassLoader to load the component classes and resources.

yan - the container that registeres the components.

NutsProcessor

public NutsProcessor(java.lang.ClassLoader cloader,
                     ResourceLoader rloader,
                     Container yan)

Create an NutsProcessor object.

Parameters:

cloader - the ClassLoader to load the component classes.

rloader - the ResourceLoader to load resources.

yan - the container that registeres the components.

Method Detail

deserialize

public java.lang.Object deserialize(java.lang.Class type,
                                    java.lang.String v)
                             throws java.lang.Throwable

Convert a string literal to an object of a certain type. A PropertyEditor is searched if the deserialization of the target type is not supported by the framework by default.

Parameters:

type - the target type.

v - the string literal.

Returns:

the object of the target type.

Throws:

java.lang.Throwable - when any error happens.

isDeserializable

public boolean isDeserializable(java.lang.Class type)

To determine if string literal can be converted to the target type. PropertyEditor is also searched if the type is not by default deserializable by the framework

Parameters:

type - the target type.

Returns:

true if convertible.

processResource

public java.lang.String[] processResource(java.lang.String resourcename)
                                   throws java.io.IOException

Process a resource from the component class loader as an xml configuration.

Parameters:

resourcename - the resource name.

Returns:

an array of dependency names that the module requires to be present in the container in order for the module to wire up properly. An empty array is returned if there's no dependency required.

Throws:

java.io.IOException - when resource reading fails.

processFile

public java.lang.String[] processFile(java.lang.String filename)
                               throws java.io.IOException

Process a config file.

Parameters:

filename - the configuration file name.

Returns:

an array of dependency names that the module requires to be present in the container in order for the module to wire up properly. An empty array is returned if there's no dependency required.

Throws:

java.io.IOException - if file reading fails.

processFile

public java.lang.String[] processFile(java.io.File file)
                               throws java.io.IOException

Process a config file.

Parameters:

file - the configuration file.

Returns:

an array of dependency names that the module requires to be present in the container in order for the module to wire up properly. An empty array is returned if there's no dependency required. An empty array is returned if there's no dependency required.

Throws:

java.io.IOException - if file reading fails.

process

public java.lang.String[] process(java.lang.Object id,
                                  java.io.InputStream in)
                           throws java.io.IOException

Process bytes read from an InputStream.

Parameters:

id - the module id.

in - the InputStream object.

Returns:

an array of dependency names that the module requires to be present in the container in order for the module to wire up properly. An empty array is returned if there's no dependency required.

Throws:

java.io.IOException - any io error.

preInstantiate

public java.util.Map preInstantiate(Container container,
                                    java.util.Map store)

Pre-initialize eagerly instantiated components.

Parameters:

container - the container to resolve dependency for these components.

store - the Map object to collect the instantiated results. The map key is UID, which is a combination of the module id and the component id.

Returns:

reference to the Map object.

preInstantiate

public java.util.Map preInstantiate(Container container)

Pre-initialize eagerly instantiated components.

Parameters:

container - the container to resolve dependency for these components.

Returns:

the Map object to collect the instantiated results. The map key is UID, which is a combination of the module id and the component id.

preInstantiate

public java.util.Map preInstantiate(java.util.Map store)

Pre-initialize eagerly instantiated components.

Parameters:

store - the Map object to collect the instantiated results. The map key is UID, which is a combination of the module id and the component id.

Returns:

reference to the Map object.

preInstantiate

public java.util.Map preInstantiate()

Pre-initialize eagerly instantiated components.

Returns:

the Map object to collect the instantiated results. The map key is UID, which is a combination of the module id and the component id.

getLifecycleManager

public DefaultLifecycleManager getLifecycleManager()

To get the lifecycle manager used by this processor.

getContainer

public Container getContainer()

To get the container used by this processor.

getBaseDir

public java.io.File getBaseDir()

To get the base directory used by the processor.

getClassLoader

public java.lang.ClassLoader getClassLoader()

To get the ClassLoader used to load component classes.

getResourceLoader

public ResourceLoader getResourceLoader()

To get the ResourceLoader used to load resources.

registerAutoWiring

public void registerAutoWiring(java.lang.String mode_name,
                               PropertyBinder mode)

Register a property autowiring mode. Any existent mode or predefined mode with the same name will be overriden.

Parameters:

mode_name - the mode name.

mode - the PropertyBinder object encapsulating the autowiring logic.

registerAutoWiring

public void registerAutoWiring(java.lang.String mode_name,
                               ParameterBinder mode)

Register a parameter autowiring mode. Any existent mode or predefined mode with the same name will be overriden.

Parameters:

mode_name - the mode name.

mode - the ParameterBinder object encapsulating the autowiring logic.

registerDeserializer

public void registerDeserializer(java.lang.Class type,
                                 Deserializer deserializer,
                                 boolean overriding,
                                 boolean mandatory)
                          throws java.lang.IllegalArgumentException

To register a Deserializer.

Parameters:

type - the type that uses the Deserializer to convert literal string to objects of this type.

deserializer - the Deserializer object.

overriding - whether override the existent Deserializer if any.

mandatory - true if this registration has to go through.

Throws:

java.lang.IllegalArgumentException - if the registration is mandatory but not overriding and an Deserializer object is already registered for the target type.

findService

public java.lang.Object findService(java.lang.Object key)

To find the service object registered using registerService(Object, Object).

Parameters:

key - the key to the service object.

Returns:

the service object. null is returned if no object is registered under this key.

registerService

public void registerService(java.lang.Object key,
                            java.lang.Object service)

To register a service object that can be read by customized Nuts classes through the call of NutEnvironment.findService(Object).

register and unregister are thread safe.

Parameters:

key - the service key.

service - the service object.

unregisterService

public void unregisterService(java.lang.Object key)

To unregister a service object. No-op if the key is not found.

Parameters:

key - the key of the service object.

getServiceKeys

public java.util.Set getServiceKeys()

Get the set of the keys of the service objects.

registerNut

public void registerNut(java.lang.String key,
                        NutDescriptor desc)

Add an external nut descriptor for the processor to use.

Parameters:

key - the key of the nut.

desc - the descriptor.

findNut

public NutDescriptor findNut(java.lang.String key)

Get a NutDescriptor registered by putNut().

Parameters:

key - the key of the NutDescriptor.

Returns:

the NutDescriptor object. Null is returned if the key is not found.

removeNut

public void removeNut(java.lang.String key)

Unregister a NutDescriptor.

Parameters:

key - the key of the NutDescriptor.

registerVariable

public void registerVariable(java.lang.String key,
                             java.lang.Object val)

Register a variable that can be referenced in the xml file using "$varname" syntax.

Parameters:

key - the variable name.

val - the variable value.

getVariable

public java.lang.Object getVariable(java.lang.String key)

To get a variable value.

Parameters:

key - the variable name.

Returns:

the variable value. Or null if not found.

hasVariable

public boolean hasVariable(java.lang.String key)

Checks whether a variable name exists.

Parameters:

key - the variable name.

removeVariable

public void removeVariable(java.lang.String key)

To remove a registration of a variable.

Parameters:

key - the variable name.

getNutKeys

public java.util.Set getNutKeys()

Get the set of keys of Nut descriptors.

getParameterWiring

public ParameterBinder getParameterWiring()

Get the default parameter auto wiring mode.

setParameterWiring

public void setParameterWiring(ParameterBinder param_wiring)

Set the default parameter auto-wiring mode.

Parameters:

param_wiring - the wiring mode. Null if auto-wiring is disabled.

getPropertyWiring

public PropertyBinder getPropertyWiring()

Get the default property auto-wiring mode.

setPropertyWiring

public void setPropertyWiring(PropertyBinder prop_wiring)

Set the default property auto-wiring mode.

Parameters:

prop_wiring - the wiring mode. Null if auto-wiring is disabled.

getSingletonMode

public SingletonMode getSingletonMode()

Get the default singleton mode.

setSingletonMode

public void setSingletonMode(SingletonMode singleton_mode)

Set the default singleton mode.

Parameters:

singleton_mode - the singleton mode. Null if prototype is used.

createMetaProcessor

public NutsProcessor createMetaProcessor(java.lang.ClassLoader loader,
                                         ResourceLoader rloader)

Create an NutsProcessor object that's gonna be used to load meta configuration of Nut classes.

The default singleton mode is "off" and the default parameter auto-wiring mode is "bytype".

All the service objects and externally registered nuts descriptors will be copied to this new NutsProcessor object.

It is fine to create an NutsProcessor object by calling the constructor directly. Any NutsProcessor object can be used to interpret meta configuration.

This method just makes it more convenient to set the default settings and copy the existing service objects and externally registered nut descriptors.

Parameters:

loader - The class loader to load classes.

rloader - the ResourceLoader to load resources.

Returns:

the new NutsProcessor object.

createMetaProcessor

public NutsProcessor createMetaProcessor(java.lang.ClassLoader loader)

Create an NutsProcessor object that's gonna be used to load meta configuration of Nut classes.

The default singleton mode is "off" and the default parameter auto-wiring mode is "bytype".

All the service objects and externally registered nuts descriptors will be copied to this new NutsProcessor object.

It is fine to create an NutsProcessor object by calling the constructor directly. Any NutsProcessor object can be used to interpret meta configuration.

This method just makes it more convenient to set the default settings and copy the existing service objects and externally registered nut descriptors.

Parameters:

loader - The class loader to load classes and resources.

Returns:

the new NutsProcessor object.

createMetaInterpreter

public NutsProcessor createMetaInterpreter()

Create an NutsProcessor object that's gonna be used to load meta configuration of Nut classes.

The component classloader is used to load classes.

The default singleton mode is "off" and the default parameter auto-wiring mode is "bytype".

All the service objects and externally registered nuts descriptors will be copied to this new NutsProcessor object.

It is fine to create an NutsProcessor object by calling the constructor directly. Any NutsProcessor object can be used to interpret meta configuration.

This method just makes it more convenient to set the default settings and copy the existing service objects and externally registered nut descriptors.

Returns:

the new NutsProcessor object.

loadNutsFromContainer

public void loadNutsFromContainer(Container nuts)

Load descriptors of the nut classes registered in a Container.

Parameters:

nuts - the container containing nut components.

loadNutsMetaFile

public void loadNutsMetaFile(java.lang.ClassLoader loader,
                             ResourceLoader rloader,
                             java.lang.String filename)
                      throws java.io.IOException

Load a configuration file that wires Nut classes. The Nut descriptors and their ids loaded from this file will be used during interpretation of regular configuration files for components.

By default, singleton mode in a nuts meta file is disabled.

Parameters:

loader - the class loader to load classes during interpretation.

rloader - the

filename - the config file containing the nuts class wiring.

Throws:

java.io.IOException - when file reading fails.

loadNutsMetaData

public void loadNutsMetaData(java.lang.Object id,
                             java.lang.ClassLoader loader,
                             ResourceLoader rloader,
                             java.io.InputStream in)
                      throws java.io.IOException

Load configuration information from an InputStream and wires Nut classes. The Nut descriptors and their ids loaded from this InputStream will be used during interpretation of regular configuration files for components.

By default, singleton mode is disabled.

Parameters:

loader - the class loader to load classes during interpretation.

rloader - the ResourceLoader to load resources during interpretation.

in - the stream containing meta configuration information.

Throws:

java.io.IOException - when file reading fails.

loadNutsMetaFile

public void loadNutsMetaFile(java.lang.String filename)
                      throws java.io.IOException

Load a configuration file that wires Nut classes. The Nut descriptors and their ids loaded from this file will be used during interpretation of regular configuration files for components.

By default, singleton mode in a nuts meta file is disabled.

The component classloader is used to load these nuts classes.

Parameters:

filename - the config file containing the nuts class wiring.

Throws:

java.io.IOException - when file reading fails.

loadNutsMetaData

public void loadNutsMetaData(java.lang.Object id,
                             java.io.InputStream in)
                      throws java.io.IOException

Load configuration information from an InputStream and wires Nut classes. The Nut descriptors and their ids loaded from this InputStream will be used during interpretation of regular configuration files for components.

By default, singleton mode is disabled.

The component classloader is used to load these nuts classes.

Parameters:

in - the stream containing meta configuration information.

Throws:

java.io.IOException - when file reading fails.

loadNutsMetaResource

public void loadNutsMetaResource(java.lang.String resourcename)
                          throws java.io.IOException

Load configuration information from a resource loaded by the component class loader. Nuts classes are wired using this configuration information.

The Nut descriptors and their ids loaded from this InputStream will be used during interpretation of regular configuration files for components.

By default, singleton mode is disabled.

The component classloader is used to load these nuts classes.

Parameters:

resourcename - the name of the resource containing meta configuration information.

Throws:

java.io.IOException - when file reading fails.