com.ail.core
Class CoreProxy

java.lang.Object
  com.ail.core.CoreProxy

All Implemented Interfaces:

ConfigurationOwner, CoreUser, java.io.Serializable

public class CoreProxy
extends java.lang.Object
implements CoreUser, ConfigurationOwner

This class acts as a proxy for those who need to access some of the Core's services, but for whatever reason cannot (or do not want to) implement CoreUser themselves.

The versionEffectiveDate of the proxy is taken to be the date at which it was instantiated.

Version:

$Revision: 1.13 $

See Also:

Serialized Form

Field Summary

static java.lang.String

DefaultNamespace

Constructor Summary

CoreProxy()
Default constructor.

CoreProxy(java.lang.String namespace)
Construct a proxy to work against a specific configuration namespace.

CoreProxy(java.lang.String namespace, CoreUser coreuser)
Construct a proxy for a specific namespace, and inherit all other settings (version effective date, security principal etc) from an instance of CoreUser.

CoreProxy(java.lang.String namespace, VersionEffectiveDate ved, java.security.Principal securityPrincipal)
Create a core proxy with a specific configuration namespace and version effective date.

Method Summary

void	closePersistenceSession() Close the open session associated with the current thread and commit.
<T extends Type> T	create(T type) Create a persistent copy of an object.
void	delete(Type type) Delete one or more objects from persistent storage.
<T> T	fromXML(java.lang.Class<T> clazz, XMLString xml) Transform XML into an object.
byte[]	generateDocument(java.lang.String productName, java.lang.String documentDefinitionName, Type model) Generate a document and return it as a byte[].
Configuration	getConfiguration() Get a copy of the CoreProxy's current configuration.
java.lang.String	getConfigurationNamespace() Get the CoreProxy's namespace.
java.util.Collection<java.lang.String>	getConfigurationNamespaceParent() Return a list of the namespace(s) of the parent(s) of this configuration.
java.util.Collection<java.lang.String>	getConfigurationSource() Return the source of the configuration being used by this instance of core.
Core	getCore() Get the instance of Core being used by this proxy.
Group	getGroup(java.lang.String name) Fetch the named group the from current configuration.
Parameter	getParameter(java.lang.String name) Fetch the named parameter from current configuration.
java.util.Properties	getParametersAsProperties(java.lang.String name) Fetch the value of the named parameter from current configuration.
java.lang.String	getParameterValue(java.lang.String name) Fetch all the Parameters in a group and return them as a java.util.Properties.
java.lang.String	getParameterValue(java.lang.String name, java.lang.String defaultValue) Return the value of a parameter or a default if it is null.
java.security.Principal	getSecurityPrincipal() Get the security principal associated with this instance.
VersionEffectiveDate	getVersionEffectiveDate() Return the version effective date associated with this proxy.
<T extends Type> T	load(java.lang.Class<T> type, long systemId) Load a specific instance of a type by ID.
void	logDebug(java.lang.String message)
void	logDebug(java.lang.String message, java.lang.Throwable cause) Output a message to the Debug logging channel.
void	logError(java.lang.String message)
void	logError(java.lang.String message, java.lang.Throwable cause) Output a message to the Error logging channel.
void	logFatal(java.lang.String message)
void	logFatal(java.lang.String message, java.lang.Throwable cause) Output a message to the Fatal logging channel.
void	logInfo(java.lang.String message)
void	logInfo(java.lang.String message, java.lang.Throwable cause) Output a message to the Info logging channel.
void	logWarning(java.lang.String message)
void	logWarning(java.lang.String message, java.lang.Throwable cause) Output a message to the Warning logging channel.
AbstractCommand	newCommand(java.lang.String commandName) Create a instance of the named command object.
java.lang.Object	newObject(java.lang.String objectName) Create a instance of the named object.
Type	newProductType(java.lang.String productName) Instantiate the default type associated with a product.
Type	newProductType(java.lang.String productName, java.lang.String typeName) Instantiate a type associated with a product.
Type	newType(java.lang.String typeName) Create a instance of the named type object.
void	openPersistenceSession() Initiate a persistence session.
java.util.List<?>	query(java.lang.String queryName, java.lang.Object... queryArgs) Query persistent storage for the collection of objects returned by a query.
Type	queryUnique(java.lang.String queryName, java.lang.Object... queryArgs) Query persistent storage for the single object returned by a query.
void	resetConfiguration() Reset the CoreProxy's configuration to its factory default settings.
boolean	resetConfiguration(java.lang.String configOwnerClassName) Reset the configuration for a named class.
void	resetCoreConfiguration() Reset the core's configuration to its factory default settings.
void	setConfiguration(Configuration config) Update the persisted copy of the CoreProxy's configuration.
void	setSecurityPrincipal(java.security.Principal securityPrincipal) Set the security principal using the proxy
void	setVersionEffectiveDate(VersionEffectiveDate ved) Set the version effective date for the proxy to a specific date.
void	setVersionEffectiveDateToNow() Set the version effective date to the date now.
XMLString	toXML(java.lang.Object obj) Transform an object into its XML representation.
<T extends Type> T	update(T type) Update the persistent copy of an object from its in memory copy.

Methods inherited from class java.lang.Object

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

Field Detail

DefaultNamespace

public static final java.lang.String DefaultNamespace

See Also:

Constant Field Values

Constructor Detail

CoreProxy

public CoreProxy()

Default constructor. This creates a core proxy with the default configation namespace ("com.ail.core.CoreProxy"), a default version effective date of Date.now() and a security principal set to null.

CoreProxy

public CoreProxy(java.lang.String namespace)

Construct a proxy to work against a specific configuration namespace. The proxy's version effective date will be set to now (Date.now()), the security principal will default to null.

Parameters:

namespace - Configuration namespace.

CoreProxy

public CoreProxy(java.lang.String namespace,
                 CoreUser coreuser)

Construct a proxy for a specific namespace, and inherit all other settings (version effective date, security principal etc) from an instance of CoreUser.

Parameters:

namespace - Configuration namespace to be used.

coreuser - Provides other settings.

CoreProxy

public CoreProxy(java.lang.String namespace,
                 VersionEffectiveDate ved,
                 java.security.Principal securityPrincipal)

Create a core proxy with a specific configuration namespace and version effective date.

Parameters:

namespace - configuration namespace to be used.

ved - version effective date.

securityPrincipal - Security principal to apply.

Method Detail

getVersionEffectiveDate

public VersionEffectiveDate getVersionEffectiveDate()

Return the version effective date associated with this proxy.

Specified by:

getVersionEffectiveDate in interface CoreUser

Returns:

The version effective date.

setVersionEffectiveDate

public void setVersionEffectiveDate(VersionEffectiveDate ved)

Set the version effective date for the proxy to a specific date.

Parameters:

ved - New date to run as.

setVersionEffectiveDateToNow

public void setVersionEffectiveDateToNow()

Set the version effective date to the date now.

getSecurityPrincipal

public java.security.Principal getSecurityPrincipal()

Get the security principal associated with this instance.

Specified by:

getSecurityPrincipal in interface CoreUser

Returns:

The associated security principal - if defined, null otherwise.

setSecurityPrincipal

public void setSecurityPrincipal(java.security.Principal securityPrincipal)

Set the security principal using the proxy

Parameters:

securityPrincipal -

newCommand

public AbstractCommand newCommand(java.lang.String commandName)

Create a instance of the named command object. The named command is looked up in the current configuration, and created from the specification held.

Parameters:

commandName - The name of the command to create.

Returns:

The command object ready for use.

newType

public Type newType(java.lang.String typeName)

Create a instance of the named type object. The named type is looked up in the current configuration, and created from the specification held.

Parameters:

typeName - The name of the type to create.

Returns:

The type object ready for use.

newObject

public java.lang.Object newObject(java.lang.String objectName)

Create a instance of the named object. The named object is looked up in the current configuration, and created from the specification held.

Parameters:

objectName - The name of the object to create.

Returns:

The object ready for use.

logDebug

public void logDebug(java.lang.String message,
                     java.lang.Throwable cause)

Output a message to the Debug logging channel. Messages written to this channel are of interest to developers, and to anyone trying to debug a system problem. The channel would generally only be turned on when a problem is being investigated.

Parameters:

message - The text of the message to be output.

logDebug

public void logDebug(java.lang.String message)

logInfo

public void logInfo(java.lang.String message,
                    java.lang.Throwable cause)

Output a message to the Info logging channel. This channel is designed to take messages that are of interest during normal operations. For example, "System ready", "Configuration reloaded".

Parameters:

message - The text of the message to be output.

logInfo

public void logInfo(java.lang.String message)

logWarning

public void logWarning(java.lang.String message,
                       java.lang.Throwable cause)

Output a message to the Warning logging channel. Messages written to this channel indicate that something unexpected occurred, but that it was dealt with and is not thought (by the developer) to be if great importance.

Parameters:

message - The text of the message to be output.

logWarning

public void logWarning(java.lang.String message)

logError

public void logError(java.lang.String message,
                     java.lang.Throwable cause)

Output a message to the Error logging channel. The error channel is reserved for messages that describe serious system problems. The problem didn't stop processing, but is significant enough to require investigation.

Parameters:

message - The text of the message to be output.

logError

public void logError(java.lang.String message)

logFatal

public void logFatal(java.lang.String message,
                     java.lang.Throwable cause)

Output a message to the Fatal logging channel. An error is fatal if it stops the operation being processed. For example, if the systems configuration information is defined in an inconsistent way a fatal error is generated.

Parameters:

message - The text of the message to be output.

logFatal

public void logFatal(java.lang.String message)

fromXML

public <T> T fromXML(java.lang.Class<T> clazz,
                     XMLString xml)
          throws XMLException

Transform XML into an object. The XMLString is taken to be an xml representation of an instance of the specified class. This method translates the XML into an instance of the class and returns that instance.

Parameters:

clazz - The Class represented by xml

xml - The XML representing and instance of clazz

Returns:

an instance of clazz built up from xml

Throws:

XMLException

toXML

public XMLString toXML(java.lang.Object obj)

Transform an object into its XML representation.

Parameters:

obj - The object to be transformed.

Returns:

An XMLString representing obj

resetConfiguration

public boolean resetConfiguration(java.lang.String configOwnerClassName)

Reset the configuration for a named class. This utility method can be used to reset a named configuration owner to its factory default settings.

Parameters:

configOwnerClassName - The fully qualified name of the class to reset the config for.

setConfiguration

public void setConfiguration(Configuration config)

Update the persisted copy of the CoreProxy's configuration.

Specified by:

setConfiguration in interface ConfigurationOwner

Parameters:

config - New configuration.

getConfiguration

public Configuration getConfiguration()

Get a copy of the CoreProxy's current configuration.

Specified by:

getConfiguration in interface ConfigurationOwner

Returns:

The current configuration.

getConfigurationNamespace

public java.lang.String getConfigurationNamespace()

Get the CoreProxy's namespace.

Specified by:

getConfigurationNamespace in interface CoreUser

Returns:

Namespace string

resetCoreConfiguration

public void resetCoreConfiguration()

Reset the core's configuration to its factory default settings.

resetConfiguration

public void resetConfiguration()

Reset the CoreProxy's configuration to its factory default settings.

Specified by:

resetConfiguration in interface ConfigurationOwner

newProductType

public Type newProductType(java.lang.String productName)

Instantiate the default type associated with a product. Each product must define a default type. This is the type (generally) instantiated at the beginning of the lifecycle.

Parameters:

productName - The name of the product to instantiate for.

Returns:

The instantiated type.

Since:

2.0

newProductType

public Type newProductType(java.lang.String productName,
                           java.lang.String typeName)

Instantiate a type associated with a product. A product must define at least one type (see newProductType(String)), but may define any number of additional types for use during its lifecycle; this method is used to instantiate specific types by name.

For example, a complex insurance product may define several different types to describe the assets the product covers. A commercial combined product might define a stock asset, a vehicle asset, a safe asset, etc. Each of these is described within the product as a separate named type. A client would use this method to instantiate these different types as and when they needed to be added to an instance of a commercial combined policy.

Parameters:

productName - The product "owning" the type.

typeName - The name of type to be instantiated.

Returns:

The instantiated type.

Since:

2.0

create

public <T extends Type> T create(T type)

Create a persistent copy of an object.

Parameters:

The - object to be persisted.

Returns:

The object as it was persisted

Since:

2.0

update

public <T extends Type> T update(T type)

Update the persistent copy of an object from its in memory copy.

Parameters:

object - The object to be written to persistent storage.

Returns:

The object as persisited.

Since:

2.0

delete

public void delete(Type type)

Delete one or more objects from persistent storage.

Parameters:

object - Object to be deleted

Throws:

VersionException - If the version object is badly defined, or relates to a version that does not exist.

Since:

2.0

load

public <T extends Type> T load(java.lang.Class<T> type,
                               long systemId)

Load a specific instance of a type by ID. This has the same effect as a named query with the following query: from <type> where systemId=<systemId>.

Parameters:

type - The type to be loaded

systemId - the systemId of the instance to load.

Returns:

The loaded type

Since:

2.0

query

public java.util.List<?> query(java.lang.String queryName,
                               java.lang.Object... queryArgs)

Query persistent storage for the collection of objects returned by a query. The query iteself is referenced by name only. This name is interpreted by the underlying persistence engine and resolved to an actual query.

Parameters:

queryName - The name of the query to be executed.

queryArgs - Arguments to be used by the query.

Returns:

The results of the query.

Throws:

VersionException - The version argument is either badly defined, or relates to a version that does not exist.

Since:

2.0

queryUnique

public Type queryUnique(java.lang.String queryName,
                        java.lang.Object... queryArgs)

Query persistent storage for the single object returned by a query. The query itself is referenced by name only. This name is interpreted by the underlying persistence engine and resolved to an actual query.

Parameters:

queryName - The name of the query to be executed.

queryArgs - Arguments to be used by the query.

Returns:

The results of the query.

Throws:

VersionException - The version argument is either badly defined, or relates to a version that does not exist.

Since:

2.0

openPersistenceSession

public void openPersistenceSession()

Initiate a persistence session. All persistence related methods need to operate within the context of a session. This call generally corresponds to the start of a transaction. The session is associated with the calling thread, so any persistent methods made within the same thread before closePersistenceSession() are performed within one transaction.

closePersistenceSession

public void closePersistenceSession()

Close the open session associated with the current thread and commit.

See Also:

openPersistenceSession()

getGroup

public Group getGroup(java.lang.String name)

Fetch the named group the from current configuration. The "current configuration" is defined by the configuration namespace and the version effective date. The namespace is taken either from the core user if they implement ConfigurationOwner, or from the core itself. The versionEffectiveDate comes from the core user.

The group's name may be dot separated indicating that the group is nested within other groups.

Parameters:

name - The name of the group to be returned.

name -

Returns:

The configuration group, or null if one is not defined for this namespace and version effective date.

Since:

2.0

getConfigurationSource

public java.util.Collection<java.lang.String> getConfigurationSource()

Return the source of the configuration being used by this instance of core. As configurations optionally have "parent" configuration that they inherit from, this method returns a collection of sources with one element for each configuration in the hierarchy.

Returns:

The sources from which the configuration was loaded.

getConfigurationNamespaceParent

public java.util.Collection<java.lang.String> getConfigurationNamespaceParent()

Return a list of the namespace(s) of the parent(s) of this configuration.

Returns:

List of namespaces which are parents to the current namespace.

getParameter

public Parameter getParameter(java.lang.String name)

Fetch the named parameter from current configuration. The "current configuration" is defined by the configuration namespace and the version effective date. The namespace is taken either from the core user if they implement ConfigurationOwner, or from the core itself. The versionEffectiveDate comes from the core user.

The parameter's name may be dot seperated indicating that the parameter is nested within one of more groups.

Parameters:

name - The name of the parameter to be returned.

Returns:

The parameter, or null if one is not defined for this namespace and version effective date.

Since:

2.0

getParametersAsProperties

public java.util.Properties getParametersAsProperties(java.lang.String name)

Fetch the value of the named parameter from current configuration. The "current configuration" is defined by the configuration namespace and the version effective date. Note: The following two pieces of code are exactly equivalent:

1. String value=null;
Parameter p=core.getParameter("paramName");
if (p!=null) {
value=p.getValue();
}
2. String value=core.getParameterValue("paramName");

Parameters:

name - The name of the parameter to return a value for.

Returns:

The parameter's value, or null if it is not defined for this namespace and version effective date.

Since:

2.0

getParameterValue

public java.lang.String getParameterValue(java.lang.String name)

Fetch all the Parameters in a group and return them as a java.util.Properties. This is a utility method returns the parameters in a named group and creates a Properties object with them. Each Parameter's name and value attributes are mapped into a property in the Properties object.

If the group specified does not exist, null is returned. If the group does exist but contains no Parameters, an empty Properties object is returned.

Parameters:

name - The name of the group whose parameters will be used.

Returns:

The parameters as properties, or null.

Since:

2.0

getParameterValue

public java.lang.String getParameterValue(java.lang.String name,
                                          java.lang.String defaultValue)

Return the value of a parameter or a default if it is null.

Parameters:

name - The name of the parameter

defaultValue - The default value

Returns:

The parameter's value, or the value of default if it is undefined.

Since:

2.0

See Also:

getParameterValue(java.lang.String)

generateDocument

public byte[] generateDocument(java.lang.String productName,
                               java.lang.String documentDefinitionName,
                               Type model)

Generate a document and return it as a byte[]. The product named "productName" is assumed to include a document definition by the name "documentDefinition". Document definitions define all of the information that the generator needs in order to render a document except for dynamic data - this is provided my model.

The type of document returned (pdf, rtf, word, etc) is determined by the document definition.

This method should be assumed to work entirely in memory - i.e. it does not persist the document at all.

A loose contract exist between the document definition and the model. A definition is written with the expectation that it can take whatever dynamic data it needs from the model it is given. Generation will fail if the model passed in does not match the definition's expectations.

Parameters:

productName - The name of product which 'owns' the document definition.

documentDefinitionName - the name of the definition to use.

model - The dynamic data satisfying references in the document definition.

Returns:

The rendered document.

getCore

public Core getCore()

Get the instance of Core being used by this proxy.

Returns:

This proxy's core