simple.http.load
Class LoaderEngine

java.lang.Object
  extended by java.rmi.server.RemoteObject
      extended by java.rmi.server.RemoteServer
          extended by java.rmi.server.UnicastRemoteObject
              extended by simple.http.load.LoaderEngine
All Implemented Interfaces:
java.io.Serializable, java.rmi.Remote, LoaderManager, ResourceEngine
Direct Known Subclasses:
MapperEngine

public class LoaderEngine
extends java.rmi.server.UnicastRemoteObject
implements ResourceEngine

The LoaderEngine is used to load Service implementations into the system so that they can be executed by a ProtocolHandler. The LoaderEngine is a LoaderManager and thus can be exported to a remote process where it can be managed/administered.

This will retrieve linked Service objects based on the simple.util.Resolver object. So the later the link is made the higher its priority. Each of the methods of the LoaderManager are governed by access control. This is so that Service objects cannot access the methods of the LoaderEngine and change the configuration.

The permission required for access to the LoaderEngine is the LoaderPermission. There are three actions that can be granted using this permission. First is "load" permission which grants permission for the load methods and the unload method. The second is "link" this grants the permission to use the link and unlink methods. The final action token is "update" which grants permission for the update and remove methods.

Monitoring activity within the LoaderEngine can be done by registering a Loader. This enables the loader to recieve updates on the configuration of the loader engine as it changes. This needs LoaderPermission with the "update" action.

Author:
Niall Gallagher
See Also:
Service, Resolver, Serialized Form

Field Summary
protected  Context context
          This is the context this loader engine operates from.
protected  simple.http.load.Processor delegate
          This is used to update any Loader objects.
protected  simple.http.load.Profile profile
          This contains the configuration of the loader engine.
protected  simple.http.load.Registry registry
          This contains the loaded Service's.
protected  Resolver resolver
          The Resolver for the linked classes.
 
Fields inherited from class java.rmi.server.RemoteObject
ref
 
Constructor Summary
  LoaderEngine()
          Constructor for the LoaderEngine that uses the class loader of the current instance to load the services.
  LoaderEngine(Context context)
          Constructor for the LoaderEngine that uses the class loader of the current instance to load the services.
protected LoaderEngine(Context context, java.io.File path)
          Constructor for the LoaderEngine takes a file classpath.
  LoaderEngine(Context context, java.net.URL codebase)
          Constructor for the LoaderEngine that uses the class loader of the current instance to load the services.
  LoaderEngine(Context context, java.net.URL[] codebase)
          Constructor for the LoaderEngine takes a URL classpath.
 
Method Summary
 void link(java.lang.String pattern, java.lang.String name)
          This is used to link a Service to a wild card pattern.
 void link(java.lang.String pattern, java.lang.String name, int pos)
          This is used to link a Service to a wild card pattern.
 void load(java.lang.String name, java.lang.String className)
          This loads the class into the system.
 void load(java.lang.String name, java.lang.String className, java.lang.Object data)
          This loads the class into the system.
 void load(java.lang.String name, java.lang.String className, java.lang.Object[] data)
          This loads the class into the system.
 Resource lookup(java.lang.String name)
          This will look for and retrieve the requested resource.
 void remove(java.lang.String name)
          This is used to terminate updates on a Loader object which has previously registered for updates.
 Resource resolve(java.lang.String target)
          This will look for and retrieve the requested resource.
 void unlink(Match match)
          This is used to unlink a loaded Service that was linked to the specified match.
 void unlink(java.lang.String pattern)
          This is used to unlink a loaded Service that was linked to the specified pattern.
 void unload(java.lang.String name)
          When an instance has been loaded by the load method this can be used to purge it from the system and subsequently remove all links to it.
 void update(java.lang.String name, Loader loader)
          This is used to insert a Loader object which is used to recieve updates on the configuration.
 
Methods inherited from class java.rmi.server.UnicastRemoteObject
clone, exportObject, exportObject, exportObject, unexportObject
 
Methods inherited from class java.rmi.server.RemoteServer
getClientHost, getLog, setLog
 
Methods inherited from class java.rmi.server.RemoteObject
equals, getRef, hashCode, toString, toStub
 
Methods inherited from class java.lang.Object
finalize, getClass, notify, notifyAll, wait, wait, wait
 

Field Detail

resolver

protected Resolver resolver
The Resolver for the linked classes.


delegate

protected simple.http.load.Processor delegate
This is used to update any Loader objects.


context

protected Context context
This is the context this loader engine operates from.


registry

protected simple.http.load.Registry registry
This contains the loaded Service's.


profile

protected simple.http.load.Profile profile
This contains the configuration of the loader engine.

Constructor Detail

LoaderEngine

public LoaderEngine()
             throws java.io.IOException
Constructor for the LoaderEngine that uses the class loader of the current instance to load the services. The semantics will be similar to Class.forName.

This will use an empty array of URL objects so that this instances loader is always used to retrieve the byte codes for referenced Service objects.

Throws:
java.io.IOException - this is thrown if the is an I/O problem with the RMI runtime or generating the classpath

LoaderEngine

public LoaderEngine(Context context)
             throws java.io.IOException
Constructor for the LoaderEngine that uses the class loader of the current instance to load the services. The semantics will be similar to Class.forName.

This will use an array of URL objects, which contains only the current working directory as the codebase to load the referenced Service objects.

Parameters:
context - used to acquire the codebase and to provide Service objects with a view of the file system
Throws:
java.io.IOException - this is thrown if the is an I/O problem with the RMI runtime or generating the classpath

LoaderEngine

protected LoaderEngine(Context context,
                       java.io.File path)
                throws java.io.IOException
Constructor for the LoaderEngine takes a file classpath. This will load the code with the semantics of the Class.forName before trying to load the code from the specified classpath. To keep consistant the LoaderEngine(Context, URL) should be used to specify a single codebase source instead of this.

This will use an array of URL objects, which contains only the specified local directory as a codebase to load the referenced Service objects.

Parameters:
context - used to provide a view of the file system
path - this is the file classpath that all the code for the Service implementations is loaded
Throws:
java.io.IOException - this is thrown if the is an I/O problem with the RMI runtime or generating the classpath

LoaderEngine

public LoaderEngine(Context context,
                    java.net.URL codebase)
             throws java.io.IOException
Constructor for the LoaderEngine that uses the class loader of the current instance to load the services. The semantics will be similar to Class.forName. When a ProtocolHandler wants to create an instance it only needs to provide the codebase and context.

This will use an array of URL objects, which contains only the specified codebase URL as the codebase to load the referenced Service objects.

Parameters:
context - used to provide a view of the file system
codebase - this is the URL classpath that all the code for the Resource implementations is loaded
Throws:
java.io.IOException - this is thrown if the is an I/O problem with the RMI runtime or generating the classpath

LoaderEngine

public LoaderEngine(Context context,
                    java.net.URL[] codebase)
             throws java.io.IOException
Constructor for the LoaderEngine takes a URL classpath. This URL classpath is where the implementation objects are loaded from. If the suggested URL classpath is not well formed then a MalformedURLException is thrown. This will load the code with the semantics of the Class.forName before trying to load the code from a URL. When a ProtocolHandler wants to create an instance it only need create a list of URL locations, which can be used to act as the classpath.

This will create a URLClassLoader using the given set of URL objects. The loading of the Resource objects will follow the semantics of the URLClassLoader(URL[]) instance.

Parameters:
context - used to provide a view of the file system
codebase - this is the URL classpath that all the code for the Resource implementations is loaded
Throws:
java.io.IOException - this is thrown if the is an I/O problem with the RMI runtime or generating the classpath
Method Detail

update

public void update(java.lang.String name,
                   Loader loader)
This is used to insert a Loader object which is used to recieve updates on the configuration. The loader can be a remote object which enables the local instance to to communicate its state to a remote administration utility. Once registered the Loader will recieve an immedidate update of the managers layout.

This throws a SecurityException if the caller does not have the LoaderPermission with the "update" token. This ensures that any Loader instances from an untrusted codebase cannot register.

Specified by:
update in interface LoaderManager
Parameters:
loader - this is the Loader object that will recieve updates on state changes
Throws:
java.lang.SecurityException - if the caller does not have the permission to register the Loader

remove

public void remove(java.lang.String name)
This is used to terminate updates on a Loader object which has previously registered for updates. If the Loader wishes to resume updates it must register again using the update method.

This throws a SecurityException if the caller does not have the LoaderPermission with the "update" token. This ensures that any Loader instances from an untrusted codebase cannot remove objects that have registered.

Specified by:
remove in interface LoaderManager
Parameters:
name - this is the name of the Loader that is terminating updates
Throws:
java.lang.SecurityException - if the caller does not have the permission to register the Loader

load

public void load(java.lang.String name,
                 java.lang.String className)
          throws LoadingException
This loads the class into the system. This will attempt to locate and load the byte codes for a Resource implementation identified by the class name. If the class can not be loaded ClassNotFoundException is thrown. The fully qualified package name must be given.

Once the Service class has been loaded it is used to create an instance. This instance can then have links established to it. The link is created using the unique name of the instance specified and a wild pattern.

Specified by:
load in interface LoaderManager
Parameters:
name - this is the unique name given to the instance
className - the fully qualified service class name
Throws:
LoadingException - thrown if the class cannot be located or loaded

load

public void load(java.lang.String name,
                 java.lang.String className,
                 java.lang.Object data)
          throws LoadingException
This loads the class into the system. This will attempt to locate and load the byte codes for a Resource implementation identified by the class name. If the class can not be loaded ClassNotFoundException is thrown. The fully qualified package name must be given.

Once the Service class has been loaded it is used to create an instance. This instance can then have links established to it. The link is created using the unique name of the instance specified and a wild pattern.

Specified by:
load in interface LoaderManager
Parameters:
name - this is the unique name given to the instance
className - the fully qualified service class name
data - this is a parameter used for initialization
Throws:
LoadingException - thrown if the class cannot be located or loaded

load

public void load(java.lang.String name,
                 java.lang.String className,
                 java.lang.Object[] data)
          throws LoadingException
This loads the class into the system. This will attempt to locate and load the byte codes for a Resource implementation identified by the class name. If the class can not be loaded ClassNotFoundException is thrown. The fully qualified package name must be given.

Once the Service class has been loaded it is used to create an instance. This instance can then have links established to it. The link is created using the unique name of the instance specified and a wild pattern. This method also allows an object to be issued to the new service instance for configuration purposes.

Specified by:
load in interface LoaderManager
Parameters:
name - this is the unique name given to the instance
className - the fully qualified service class name
data - the configuration objects used by the service
Throws:
LoadingException - thrown if the class cannot be located or loaded

unload

public void unload(java.lang.String name)
When an instance has been loaded by the load method this can be used to purge it from the system and subsequently remove all links to it. If the class name specified does not correspond to a Service that had be previously loaded this will return quietly. The fully qualified package name must be given.

Specified by:
unload in interface LoaderManager
Parameters:
name - this is the name of the service object

link

public void link(java.lang.String pattern,
                 java.lang.String name)
This is used to link a Service to a wild card pattern. The Service can be linked using the patterns '*' and '?'. This will enable the resource to be isolated using a string that matches the suggested pattern.

Patterns can take the form of a string with wild characters embedded in it, for instance "*.html". Also if the class name does not belong to a previously loaded Service this should return quietly.

This throws a SecurityException if the caller does not have the LoaderPermission with the "link" action. This ensures that any Service instances loaded from an untrusted codebase cannot change the configuration settings.

Specified by:
link in interface LoaderManager
Parameters:
pattern - this is a wild string used for matching
name - this is the Service that will be identified by the pattern
Throws:
java.lang.SecurityException - if the caller does not have the permission to link the pattern

link

public void link(java.lang.String pattern,
                 java.lang.String name,
                 int pos)
This is used to link a Service to a wild card pattern. The Service can be linked using the patterns '*' and '?'. This will enable the resource to be isolated using a string that matches the suggested pattern.

Patterns can take the form of a string with wild characters embedded in it, for instance "*.html". Also if the class name does not belong to a previously loaded Service this should return quietly.

This throws a SecurityException if the caller does not have the LoaderPermission with the "link" action. This ensures that any Service instances loaded from an untrusted codebase cannot change the configuration settings.

Specified by:
link in interface LoaderManager
Parameters:
pattern - this is a wild string used for matching
name - this is the Service that will be identified by the pattern
pos - the position within the list of patterns to add the new match
Throws:
java.lang.SecurityException - if the caller does not have the permission to link the pattern

unlink

public void unlink(java.lang.String pattern)
This is used to unlink a loaded Service that was linked to the specified pattern. If that pattern was not used to match a Service then this returns quietly.

This throws a SecurityException if the caller does not have the LoaderPermission with the "link" action. This ensures that any Service instances loaded from an untrusted codebase cannot change the configuration settings.

Specified by:
unlink in interface LoaderManager
Parameters:
pattern - this is a wild string used for matching
Throws:
java.lang.SecurityException - if the caller does not have

unlink

public void unlink(Match match)
This is used to unlink a loaded Service that was linked to the specified match. If that pattern was not used to match a Service then this returns quietly.

This throws a SecurityException if the caller does not have the LoaderPermission with the "link" action. This ensures that any Service instances loaded from an untrusted codebase cannot change the configuration settings.

Specified by:
unlink in interface LoaderManager
Parameters:
match - this is the pattern match to remove from this
Throws:
java.lang.SecurityException - if the caller does not have

lookup

public Resource lookup(java.lang.String name)
This will look for and retrieve the requested resource. The target given must be the actual name for the resource. This will locate the resource and return the Resource implementation that will handle the target.

If the named service does not corrospond to a previously loaded service then this will return a resource object that will report the appropriate HTTP status and description.

Parameters:
name - this is than name of the service to retrieve
Returns:
the service implementation that has been retrieved

resolve

public Resource resolve(java.lang.String target)
This will look for and retrieve the requested resource. The target given must be in the form of a request URI. This will locate the resource and return the Resource implementation that will handle the target.

The path will be matched with a pattern that was linked to a Resource object. This uses Resolver to match the target with the Resource. This will thus match on priority of last entry. So if a resource can match two or more patterns then the last entered pattern is the one that resolves the Resource.

This will attempt to resolve the path given without striping the query of parameters. If the link does not accomodate for paths with querys or parameters the resolver will skip past the match. Some default * link should be made so that if all links fail there is some fallback resource.

Specified by:
resolve in interface ResourceEngine
Parameters:
target - the URI style path that represents the target Resource
Returns:
this returns the Resource object to handle the desired target