net.openwings.policy
Interface PolicyLoader

public interface PolicyLoader

This interface describes a utility that instantiates Policy objects and loads their saved state. Unless the location of the policy file is explicitly stated, policies are loaded from the policy path, defined by the property net.openwings.policy.path.

An implementation of this interface is obtained using the PolicyLoaderFactory. An Openwings Component can obtain a PolicyLoader object by calling the net.openwings.component.ComponentComplex.getPolicyLoader() method.

Method Summary

void	addPackageMapping(java.lang.Class policyType, java.lang.String altPackage) This method adds a mapping of a Policy interface to a package where a suitable implementation class may be found.
Policy	createNewPolicy(java.lang.Class policyType) Create a new policy object that implements the interface specified by the policyType parameter.
Policy	getPolicy(java.lang.Class policyType, java.io.File configFile) Get a policy object that implements the interface specified by the policyType parameter.
Policy	getPolicy(java.lang.Class policyType, java.lang.String name) Get a policy object that implements the interface specified by the policyType parameter.
Policy	getPolicy(java.lang.Class policyType, java.lang.String name, java.lang.ClassLoader loader) Get a policy object that implements the interface specified by the policyType parameter.
Policy	getPolicy(java.lang.Class policyType, java.net.URL location) Get a policy object that implements the interface specified by the policyType parameter.
java.util.Iterator	packageMapping(java.lang.Class policyType) Get an Iterator over the mappings of a Policy class to an implementation package.

Method Detail

addPackageMapping

public void addPackageMapping(java.lang.Class policyType,
                              java.lang.String altPackage)

This method adds a mapping of a Policy interface to a package where a suitable implementation class may be found. No check is made to verify whether the package contains a suitable class at the time the mapping is made.

The mapping of interfaces to implementations is also achievable via Java properties. For example, to specify that the implementation of interface mypackage.MyPolicy is found in package myimplpackage, set a property with name equal to the interface name, and value equal to the package name. On the command line, this would look something like this:

-Dmypackage.MyPolicy=myimplpackage

To set multiple package mappings, use a space-separated list, enclosed in quotes:

-Dmypackage.MyPolicy="myimplpackage myotherimplpackage"

Parameters:

policyType - The interface of the Policy.

altPackage - the name of a package containing an implementation of the policy interface specified in policyType.

packageMapping

public java.util.Iterator packageMapping(java.lang.Class policyType)

Get an Iterator over the mappings of a Policy class to an implementation package.

Parameters:

policyType - The interface of the Policy.

Returns:

An Iterator over the names of packages that may contain an implementation of the policy interface, or null if there is no mapping.

getPolicy

public Policy getPolicy(java.lang.Class policyType,
                        java.net.URL location)
                 throws PolicyException

Get a policy object that implements the interface specified by the policyType parameter. The name of the policy implementation class is created by appending "Impl" to the name of the interface given in the policyType argument. For example, for an interface of the class MyPolicy, the loader will attempt to load MyPolicyImpl.

The Policy object that is returned will be initialized with its configuration data. The configuration data file must be at the location specified by URL location.

Parameters:

policyType - The interface that the returned Policy object must support.

location - an URL to the policy object

Returns:

The Policy object, or null if none could be found.

Throws:

PolicyException - An exception indicating something went wrong in trying to load the Policy object or its configuration data. This exception may wrap a core JVM exception.

getPolicy

public Policy getPolicy(java.lang.Class policyType,
                        java.io.File configFile)
                 throws PolicyException

Get a policy object that implements the interface specified by the policyType parameter. The name of the policy implementation class is created by appending "Impl" to the name of the interface given in the policyType argument. For example, for an interface of the class MyPolicy, the loader will attempt to load MyPolicyImpl.

The Policy object that is returned will be initialized with its configuration data. The configuration data file must be at the location specified by File configFile.

Parameters:

policyType - The interface that the returned Policy object must support.

configFile - a file to the policy object

Returns:

The Policy object, or null if none could be found.

Throws:

PolicyException - An exception indicating something went wrong in trying to load the Policy object or its configuration data. This exception may wrap a core JVM exception.

getPolicy

public Policy getPolicy(java.lang.Class policyType,
                        java.lang.String name)
                 throws PolicyException

Get a policy object that implements the interface specified by the policyType parameter. The name of the policy implementation class is created by appending "Impl" to the name of the interface given in the policyType argument. For example, for an interface of the class MyPolicy, the loader will attempt to load MyPolicyImpl.

The Policy object that is returned will be initialized with its configuration data. Configuration data is loaded from the same location as the implementation class. Configuration data will be loaded from a resource whose name is formed by concatenating the name of the interface class, the name parameter, and ".xml". If the interface class is MyPolicy and name is Data1, the configuration data will be loaded from MyPolicyData1.xml. The configuration data file must be available on the policy path.

If there is no mapping of the policy class to one or more packages, the loader will attempt to load the implementation class from the same package as the interface.

Parameters:

policyType - The interface that the returned Policy object must support.

name - A name to identify this instance of the policy. May be null.

Returns:

The Policy object, or null if none could be found.

Throws:

PolicyException - An exception indicating something went wrong in trying to load the Policy object or its configuration data. This exception may wrap a core JVM exception.

getPolicy

public Policy getPolicy(java.lang.Class policyType,
                        java.lang.String name,
                        java.lang.ClassLoader loader)
                 throws PolicyException

Get a policy object that implements the interface specified by the policyType parameter. The name of the policy implementation class is created by appending "Impl" to the name of the interface given in the policyType argument. For example, for an interface of the class MyPolicy, the loader will attempt to load MyPolicyImpl. The class loader, if specified, will be used to load the implementation class and its configuration data.

The Policy object that is returned will be initialized with its configuration data. Configuration data is loaded from the same location as the implementation class. Configuration data will be loaded from a resource whose name is formed by concatenating the name of the interface class, the name parameter, and ".xml". If the interface class is MyPolicy and name is Data1, the configuration data will be loaded from MyPolicyData1.xml. The configuration data file must be available on the policy path.

If there is no mapping of the policy class to one or more packages, the loader will attempt to load the implementation class from the same package as the interface.

Parameters:

policyType - The interface that the returned Policy object must support.

name - A name to identify this instance of the policy. May be null.

loader - The ClassLoader to use when loading the Policy and its configuration data. If this is null, the system ClassLoader will be used.

Returns:

The Policy object, or null if none could be found.

Throws:

PolicyException - An exception indicating something went wrong in trying to load the Policy object or its configuration data. This exception may wrap a core JVM exception.

createNewPolicy

public Policy createNewPolicy(java.lang.Class policyType)
                       throws PolicyException

Create a new policy object that implements the interface specified by the policyType parameter. The name of the policy implementation class is created by appending "Impl" to the name of the interface given in the policyType argument. For example, for an interface of the class MyPolicy, the loader will attempt to load MyPolicyImpl.

The Policy object that is returned will be initialized with default values.

If there is no mapping of the policy class to one or more packages, the loader will attempt to load the implementation class from the same package as the interface.

Parameters:

policyType - The interface that the returned Policy object must support.

Returns:

The Policy object, or null if none could be found.

Throws:

PolicyException - An exception indicating something went wrong in trying to create the Policy object. This exception may wrap a core JVM exception.