gov.nih.nci.cagrid.introduce.servicetools
Class ReflectionResource

java.lang.Object
  gov.nih.nci.cagrid.introduce.servicetools.ReflectionResource

All Implemented Interfaces:

org.globus.wsrf.Resource, org.globus.wsrf.ResourceIdentifier, org.globus.wsrf.ResourceLifetime, org.globus.wsrf.ResourceProperties

Direct Known Subclasses:

TransferServiceContextResourceBase, TransferServiceResourceBase

public class ReflectionResource
extends java.lang.Object
implements org.globus.wsrf.Resource, org.globus.wsrf.ResourceProperties, org.globus.wsrf.ResourceIdentifier, org.globus.wsrf.ResourceLifetime

An implementation of ResourceProperties and ResourceIdentifier which frees the developer from having to write a getter and possibly a setter to implement every resource property (RP).

This class uses an Axis-generated JavaBean class based on the Schema definition of the RP set used by the service port type in WSDL. Since the generated class contain a JavaBean property as well as QName and Schema type metadata (such as occurence cardinality) for each RP, it is possible to automatically create ReflectionResourceProperty objects to provide an implementation of the RPs. This is what ReflectionResource does.

Advantages of using this class:

• Less errors due to forgetting to implement a resource property.
• Less code to write, so implementing a resource is faster.
• Easier maintenance when the WSDL/Schema definition changes.
• Less errors due to namespace mismatch between WSDL and code.
• Less errors thanks to the handling of a few special cases.

Usage:

The specialized resource home class should do the following when creating a resource:

1. create an object corresponding to the Schema type or element of the resource property set.
2. initialize the object by calling its setters.
3. construct the specialized ReflectionResource-based resource object.
4. call initialize on the resource, passing it the implementation bean created in 1).

Reuse approach:

• If no specialized behavior is required from the resource implementation, there is no need for a specialized class. The Home class can just create objects of type ReflectionResource.
• If specialized behavior is required from the resource implementation, it is easy to reuse this class (via inheritance or delegation) and thus achieve a clean separation of the specialized code from the RP setup code.

Typical goals when extending the class:

• to customize the resource property creation behavior for special cases not handled by this class.
• to add domain-specific behavior, public or not, to the Resource objects.

Extending ReflectionResource:

Classes directly or indirectly extending ReflectionResource property must be allow instanciation without parameter. If a parameterless constructor is present it must not do any initialization whatsoever. The reason is to decouple object creation from initialization so as to match the requirements of Resource Home classes such as ResourceHomeImpl, which, when materializing a previously stored persistent resource, creates the resource object first using a parameterless constructor, and then initializes the object. Code that creates the key of the resource automatically (for instance a UUID) - in domain-specific cases where it makes sense - should not be put inside a parameterless constructor but in an a overriding version of the initialize() method, or inside the Resource Home class. In this way a Persistent Resource object can be brought back from a passivated state and be given the ID it used to have in activated mode, as opposed to a newly generated ID.

Known limitations:

• does not set the 'nillable' JavaBean property on the ResourceProperty objects (Axis does not generate this metadatum).

This class does not provide a getter to the implementation JavaBean, because it is good practice to access the value of a resource property by obtaining the ResourceProperty object first, as opposed to calling the getters and setters of its implementation Bean.

In fact:

• some resource properties are implemented using other objects (for instance wsrl:CurrentTime is implemented via getCurrentTime, and the resource properties from wsnt:NotificationProducer are implemented directly or indirectly by a SimpleTopicList).
• the ResourceProperty object generic accessors may do extra processing such as firing change notification events (for instance if it is a ResourcePropertyTopic).

Constructor Summary

ReflectionResource()

Method Summary

protected org.globus.wsrf.ResourceProperty	createNewResourceProperty(javax.xml.namespace.QName rpQName, java.lang.Object resourceBean) Warning: this is not a callback (but maybe it should be).
protected org.globus.wsrf.ResourceProperty	createNewResourceProperty(org.globus.wsrf.ResourcePropertyMetaData metaData, java.lang.Object resourceBean) Override this callback method to specialize the implementation of the resource property value accessors on a per resource property basis.
java.util.Calendar	getCurrentTime()
java.lang.Object	getID() See ResourceIdentifier.
java.lang.Object	getResourceBean()
org.globus.wsrf.ResourcePropertySet	getResourcePropertySet() See ResourceProperties.
java.util.Calendar	getTerminationTime()
void	initialize(java.lang.Object resourceBean, javax.xml.namespace.QName resourceElementQName, java.lang.Object key) This should be called before any other resource property addition is made as it will create resource properties object based on the resource properties defined in the schema.
void	setTerminationTime(java.util.Calendar time)

Methods inherited from class java.lang.Object

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

Constructor Detail

ReflectionResource

public ReflectionResource()

Method Detail

initialize

public void initialize(java.lang.Object resourceBean,
                       javax.xml.namespace.QName resourceElementQName,
                       java.lang.Object key)
                throws org.globus.wsrf.ResourceException

This should be called before any other resource property addition is made as it will create resource properties object based on the resource properties defined in the schema. It is possible to override the implementation of certain resources properties by adding a new ResourceProperty object to the resource property set after this method has been called. This method should be called in the constructor of the concrete resource class, or shortly after the parameterless constructor has been called.

Parameters:

resourceBean - Object An instance of the Axis-generated class corresponding to the resource property set global Schema type or element (with local type) used by the port type definition. That class has JavaBean properties matching all the resource properties of the port type. The ReflectionResource constructor creates the ResourceProperty objects based on the resource bean, which JavaBean properties SHOULD thus have been initialized beforehand. This object provides an easy way to initialize the values of the resource properties.

resourceElementQName - QName The QName of the resource properties element used by the port type. This corresponds to the value of the 'wsrp:ResourceProperties' attribute. If the type of this element is anonymous (i.e. inlined in the element declaration) then this parameter is optional. If it is non-null though, its value takes precedence over Axis-generated metadata.

key - Object The resource key object for this resource. This is used to set the ID property of this object as a ResourceIdentifier, if the resource class doesn't create it automatically.

Throws:

org.globus.wsrf.ResourceException

createNewResourceProperty

protected org.globus.wsrf.ResourceProperty createNewResourceProperty(javax.xml.namespace.QName rpQName,
                                                                     java.lang.Object resourceBean)
                                                              throws java.lang.Exception

Warning: this is not a callback (but maybe it should be).

Parameters:

rpQName - QName

resourceBean - Object

Returns:

ResourceProperty

Throws:

java.lang.Exception

createNewResourceProperty

protected org.globus.wsrf.ResourceProperty createNewResourceProperty(org.globus.wsrf.ResourcePropertyMetaData metaData,
                                                                     java.lang.Object resourceBean)
                                                              throws java.lang.Exception

Override this callback method to specialize the implementation of the resource property value accessors on a per resource property basis. For instance, in the overriden version, do special processing if the QName of the property matches a special QName, or just call this base implementation otherwise.

The default behavior is to create a new ReflectionResourceProperty constructed with the QName of the resource property and the resource implementation Bean used to construct this ReflectionResource object.

This function handles a few special cases:

• If rpQName equals WSRFConstants.CURRENT_TIME, the resource property MUST use a dynamic implementation of getCurrentTime(), since time never stops changing. Therefore the resource bean callback used is not the initial resource Bean but the ReflectionResource object, which bears such an implementation of that function.
• If rpQName equals WSRFConstants.TERMINATION_TIME, the resource property created is set be nillable.

Parameters:

metaData - Meta data associated with the resource property object

resourceBean - same as passed to constructor or initialize

Throws:

java.lang.Exception

setTerminationTime

public void setTerminationTime(java.util.Calendar time)

Specified by:

setTerminationTime in interface org.globus.wsrf.ResourceLifetime

getTerminationTime

public java.util.Calendar getTerminationTime()

Specified by:

getTerminationTime in interface org.globus.wsrf.ResourceLifetime

getCurrentTime

public java.util.Calendar getCurrentTime()

Specified by:

getCurrentTime in interface org.globus.wsrf.ResourceLifetime

getResourcePropertySet

public org.globus.wsrf.ResourcePropertySet getResourcePropertySet()

See ResourceProperties.

Specified by:

getResourcePropertySet in interface org.globus.wsrf.ResourceProperties

Returns:

ResourcePropertySet

getID

public java.lang.Object getID()

See ResourceIdentifier.

Specified by:

getID in interface org.globus.wsrf.ResourceIdentifier

Returns:

Object The key of the Resource. This is useful for instance when creating an endpoint reference that must be qualified with this resource.

getResourceBean

public java.lang.Object getResourceBean()

Returns:

Object the Axis-generated Java Bean used as the main implementation of the resource state.