Apache Incubator Project Site > Apache Incubator Projects
Apollo
 

Writing a Home class

Introduction

This section will describe how to write a home for your resource class. The home is used to lookup the resource instance. It can act as a factory for creating instances upon request, or build all instances. It is meant to be the entry point for locating a resource instance.

Class Declaration

When declaring your "home" you should extend AbstractResourceHome. Extending AbstractResourceHome will provide services for caching instances and looking them up. It will also ensure that the correct interfaces are implemented so that Apollo can interact with your home.

The FileSystemHome extends AbstractResourceHome and implements Serializable:

public class FileSystemHome
        extends AbstractResourceHome
        implements Serializable

Operations

If you extend AbstractResourceHome, the only required operation you will need to implement is:

public Resource getInstance( ResourceContext resourceContext )

The getInstance(...) operation provides the ability for you to intercept the request for retrieving an instance. In the FileSystem example, we use the operation to determine if the requested resource instance is a valid filesystems (i.e. one that is being managed via WSRF); if it is not, we throw an exception.

public Resource getInstance( ResourceContext resourceContext )
            throws ResourceException,
            ResourceContextException,
            ResourceUnknownException
    {
        ResourceKey key = resourceContext.getResourceKey();
        Resource resource = null;
        try
        {
            resource = find( key );
        }
        catch ( ResourceException re )
        {
            Object id = key.getValue();
            /**
             * Determine if the passed-in key is, in fact, something we expect.
             */
            if ( id.equals( "/dev/vg00/lvol1" ) || id.equals( "/dev/vg00/lvol2" ) )
            {
                try
                {
                    resource = createInstance( key);
                }
                catch ( Exception e )
                {
                    throw new ResourceException( e );
                }
                add( key, resource );
            }
            else
            {
                throw new ResourceUnknownException( id,
                        resourceContext.getServiceName() );
            }
        }
        return resource;
    }

Notice the method makes calls to find(...) and createInstance(...). These operations are provided by the AbstractResourceHome superclass. They provide functions like caching and instantiating instances.

Note
Many of the operations in the AbstractResourceHome may be overridden in your Home class, if you have a need to extend its functionality.