You are viewing a plain text version of this content. The canonical link for it is here.
Posted to muse-commits@ws.apache.org by da...@apache.org on 2006/08/23 06:02:35 UTC
svn commit: r433870 [1/3] - in
/webservices/muse/trunk/modules/muse-core/src/org/apache/muse: core/
core/descriptor/ core/platform/ core/proxy/ core/routing/ core/serializer/
ws/wsdl/
Author: danj
Date: Tue Aug 22 21:02:32 2006
New Revision: 433870
URL: http://svn.apache.org/viewvc?rev=433870&view=rev
Log:
Cleaned up source files and finished JavaDoc for muse-core. Also finished implementation of some error
messages, tweaked some error message placeholder values, and make messages consistent. As with the milestone
releases, the descriptor types will not be included in the public API (and javadoc).
Modified:
webservices/muse/trunk/modules/muse-core/src/org/apache/muse/core/AbstractCapability.java
webservices/muse/trunk/modules/muse-core/src/org/apache/muse/core/AbstractEnvironment.java
webservices/muse/trunk/modules/muse-core/src/org/apache/muse/core/AbstractFilePersistence.java
webservices/muse/trunk/modules/muse-core/src/org/apache/muse/core/AbstractResourceClient.java
webservices/muse/trunk/modules/muse-core/src/org/apache/muse/core/Capability.java
webservices/muse/trunk/modules/muse-core/src/org/apache/muse/core/CapabilityContainer.java
webservices/muse/trunk/modules/muse-core/src/org/apache/muse/core/Environment.java
webservices/muse/trunk/modules/muse-core/src/org/apache/muse/core/Initialization.java
webservices/muse/trunk/modules/muse-core/src/org/apache/muse/core/InitializationFailure.java
webservices/muse/trunk/modules/muse-core/src/org/apache/muse/core/InitializationParameters.java
webservices/muse/trunk/modules/muse-core/src/org/apache/muse/core/Messages.properties
webservices/muse/trunk/modules/muse-core/src/org/apache/muse/core/Persistence.java
webservices/muse/trunk/modules/muse-core/src/org/apache/muse/core/Resource.java
webservices/muse/trunk/modules/muse-core/src/org/apache/muse/core/ResourceManager.java
webservices/muse/trunk/modules/muse-core/src/org/apache/muse/core/ResourceManagerListener.java
webservices/muse/trunk/modules/muse-core/src/org/apache/muse/core/Shutdown.java
webservices/muse/trunk/modules/muse-core/src/org/apache/muse/core/SimpleResource.java
webservices/muse/trunk/modules/muse-core/src/org/apache/muse/core/SimpleResourceManager.java
webservices/muse/trunk/modules/muse-core/src/org/apache/muse/core/descriptor/CapabilityDefinition.java
webservices/muse/trunk/modules/muse-core/src/org/apache/muse/core/descriptor/CapabilityDescriptor.java
webservices/muse/trunk/modules/muse-core/src/org/apache/muse/core/descriptor/DescriptorConstants.java
webservices/muse/trunk/modules/muse-core/src/org/apache/muse/core/descriptor/InitParamDescriptor.java
webservices/muse/trunk/modules/muse-core/src/org/apache/muse/core/descriptor/LoggingConfig.java
webservices/muse/trunk/modules/muse-core/src/org/apache/muse/core/descriptor/Messages.properties
webservices/muse/trunk/modules/muse-core/src/org/apache/muse/core/descriptor/PersistenceDefinition.java
webservices/muse/trunk/modules/muse-core/src/org/apache/muse/core/descriptor/PersistenceDescriptor.java
webservices/muse/trunk/modules/muse-core/src/org/apache/muse/core/descriptor/ResourceDefinition.java
webservices/muse/trunk/modules/muse-core/src/org/apache/muse/core/descriptor/ResourceDescriptor.java
webservices/muse/trunk/modules/muse-core/src/org/apache/muse/core/descriptor/RouterDefinition.java
webservices/muse/trunk/modules/muse-core/src/org/apache/muse/core/descriptor/RouterDescriptor.java
webservices/muse/trunk/modules/muse-core/src/org/apache/muse/core/descriptor/RouterPersistenceDescriptor.java
webservices/muse/trunk/modules/muse-core/src/org/apache/muse/core/descriptor/SerializerDefinition.java
webservices/muse/trunk/modules/muse-core/src/org/apache/muse/core/descriptor/SerializerDescriptor.java
webservices/muse/trunk/modules/muse-core/src/org/apache/muse/core/descriptor/SimpleCapabilityDescriptor.java
webservices/muse/trunk/modules/muse-core/src/org/apache/muse/core/descriptor/SimpleDeploymentDescriptor.java
webservices/muse/trunk/modules/muse-core/src/org/apache/muse/core/descriptor/SimplePersistenceDescriptor.java
webservices/muse/trunk/modules/muse-core/src/org/apache/muse/core/descriptor/SimpleResourceDescriptor.java
webservices/muse/trunk/modules/muse-core/src/org/apache/muse/core/descriptor/SimpleRouterDescriptor.java
webservices/muse/trunk/modules/muse-core/src/org/apache/muse/core/descriptor/SimpleSerializerDescriptor.java
webservices/muse/trunk/modules/muse-core/src/org/apache/muse/core/descriptor/WsdlConfig.java
webservices/muse/trunk/modules/muse-core/src/org/apache/muse/core/platform/AbstractIsolationLayer.java
webservices/muse/trunk/modules/muse-core/src/org/apache/muse/core/platform/IsolationLayer.java
webservices/muse/trunk/modules/muse-core/src/org/apache/muse/core/proxy/ReflectionProxyHandler.java
webservices/muse/trunk/modules/muse-core/src/org/apache/muse/core/routing/AbstractMessageHandler.java
webservices/muse/trunk/modules/muse-core/src/org/apache/muse/core/routing/CounterResourceIdFactory.java
webservices/muse/trunk/modules/muse-core/src/org/apache/muse/core/routing/MessageHandler.java
webservices/muse/trunk/modules/muse-core/src/org/apache/muse/core/routing/Messages.properties
webservices/muse/trunk/modules/muse-core/src/org/apache/muse/core/routing/ReflectionMessageHandler.java
webservices/muse/trunk/modules/muse-core/src/org/apache/muse/core/routing/ResourceIdFactory.java
webservices/muse/trunk/modules/muse-core/src/org/apache/muse/core/routing/ResourceRouter.java
webservices/muse/trunk/modules/muse-core/src/org/apache/muse/core/routing/RouterFilePersistence.java
webservices/muse/trunk/modules/muse-core/src/org/apache/muse/core/routing/SimpleResourceRouter.java
webservices/muse/trunk/modules/muse-core/src/org/apache/muse/core/serializer/ArraySerializer.java
webservices/muse/trunk/modules/muse-core/src/org/apache/muse/core/serializer/Messages.properties
webservices/muse/trunk/modules/muse-core/src/org/apache/muse/core/serializer/Serializer.java
webservices/muse/trunk/modules/muse-core/src/org/apache/muse/core/serializer/SerializerRegistry.java
webservices/muse/trunk/modules/muse-core/src/org/apache/muse/core/serializer/XmlSerializableSerializer.java
webservices/muse/trunk/modules/muse-core/src/org/apache/muse/ws/wsdl/WsdlUtils.java
Modified: webservices/muse/trunk/modules/muse-core/src/org/apache/muse/core/AbstractCapability.java
URL: http://svn.apache.org/viewvc/webservices/muse/trunk/modules/muse-core/src/org/apache/muse/core/AbstractCapability.java?rev=433870&r1=433869&r2=433870&view=diff
==============================================================================
--- webservices/muse/trunk/modules/muse-core/src/org/apache/muse/core/AbstractCapability.java (original)
+++ webservices/muse/trunk/modules/muse-core/src/org/apache/muse/core/AbstractCapability.java Tue Aug 22 21:02:32 2006
@@ -29,12 +29,17 @@
/**
*
* AbstractCapability provides a foundation for user-defined capabilities
- * that allows users to focus on their operations and capability-specific
+ * by allowing users to focus on their operations and capability-specific
* logic without having to worry about maintaining Muse components and
- * other plumbing work. This class will provide all of the basic Muse
- * components needed for normal operation and the operation dispatching
- * at runtime. The implementations of the initialization and shutdown
- * routines are mostly no-ops.
+ * other plumbing work.
+ * <br><br>
+ * The implementations of the initialization and shutdown routines are mostly
+ * no-ops. Nevertheless, if these methods are overridden by concrete capability
+ * classes, the implementations should be sure to call the parent class version
+ * (via 'super') before executing their own logic; for example, a new version
+ * of the initialize() method should always start with a call to super.initialize().
+ * As the class hierarchy grows, this ensures that startup and shutdown tasks
+ * are always performed in the proper order.
*
* @author Dan Jemiolo (danj)
*
@@ -42,10 +47,17 @@
public abstract class AbstractCapability implements Capability
{
+ //
+ // the unique URI that defines the capability within a resource type
+ //
private String _capabilityURI = null;
private Environment _environment = null;
+ //
+ // WS-A Action -> MessageHandler - the MessageHandler converts
+ // SOAP -> Java and vice versa
+ //
private Map _handlersByAction = new HashMap();
private boolean _hasBeenInitialized = false;
@@ -59,6 +71,9 @@
//
private Map _parameters = null;
+ //
+ // optional persistence mechanism for saving/re-loading state
+ //
private Persistence _persistence = null;
//
@@ -132,6 +147,10 @@
{
Persistence persistence = getPersistence();
+ //
+ // if the capability defines a persistence mechanism, we
+ // should ask it to reload any saved data
+ //
if (persistence != null)
{
ResourceManager manager = getResource().getResourceManager();
@@ -143,7 +162,9 @@
public void prepareShutdown()
throws SoapFault
{
+ //
// no default action
+ //
}
public void setCapabilityURI(String capabilityURI)
Modified: webservices/muse/trunk/modules/muse-core/src/org/apache/muse/core/AbstractEnvironment.java
URL: http://svn.apache.org/viewvc/webservices/muse/trunk/modules/muse-core/src/org/apache/muse/core/AbstractEnvironment.java?rev=433870&r1=433869&r2=433870&view=diff
==============================================================================
--- webservices/muse/trunk/modules/muse-core/src/org/apache/muse/core/AbstractEnvironment.java (original)
+++ webservices/muse/trunk/modules/muse-core/src/org/apache/muse/core/AbstractEnvironment.java Tue Aug 22 21:02:32 2006
@@ -57,7 +57,7 @@
// Used to lookup all exception messages
//
private static Messages _MESSAGES = MessagesFactory.get(AbstractEnvironment.class);
-
+
//
// Used to load resources (files, etc) in the applications's classpath
//
@@ -159,14 +159,14 @@
return new SimpleSoapClient();
}
- public ClassLoader getClassLoader()
+ public synchronized MessageHeaders getAddressingContext()
{
- return _classLoader;
+ return (MessageHeaders)_contextByThread.get(Thread.currentThread());
}
- public synchronized MessageHeaders getAddressingContext()
+ public ClassLoader getClassLoader()
{
- return (MessageHeaders)_contextByThread.get(Thread.currentThread());
+ return _classLoader;
}
public URL getDataResource(String path)
@@ -195,6 +195,11 @@
return stream;
}
+ /**
+ *
+ * @return An EPR whose URI is the value returned by getDefaultURI().
+ *
+ */
protected EndpointReference getDefaultEPR()
{
String defaultURI = getDefaultURI();
@@ -205,6 +210,7 @@
return new EndpointReference(URI.create(defaultURI));
}
+
public String getDefaultURI()
{
return _defaultURI;
@@ -215,11 +221,9 @@
* @param uriString
*
* @return The URI being targeted by the current request. This URI
- * includes an IP address rather than a host name, because
- * we often use it to create EPRs/URIs for remote users
- * based on the results of a local request. Just because the
- * initial request was local doesn't mean we should represent
- * ourselves to remote users with a local name. It also means
+ * includes an IP address rather than a host name, because we
+ * often use it to create EPRs/URIs for remote users based
+ * on the results of a local request. Returning an IP means
* that remote systems don't have to have a hosts lookup that
* includes our endpoint's machine.
*
@@ -240,11 +244,13 @@
throw new RuntimeException(error);
}
+ //
+ // create new URI and s/host/IP
try
{
uri = new URI(uri.getScheme(),
uri.getUserInfo(),
- ip,
+ ip,
uri.getPort(),
uri.getPath(),
uri.getQuery(),
@@ -287,16 +293,6 @@
public SoapClient getSoapClient()
{
return _soapClient;
- }
-
- public EndpointReference getTargetEPR()
- {
- MessageHeaders headers = getAddressingContext();
-
- if (headers == null)
- throw new IllegalStateException(_MESSAGES.get("NoRequestContext"));
-
- return headers.getToAddress();
}
/**
Modified: webservices/muse/trunk/modules/muse-core/src/org/apache/muse/core/AbstractFilePersistence.java
URL: http://svn.apache.org/viewvc/webservices/muse/trunk/modules/muse-core/src/org/apache/muse/core/AbstractFilePersistence.java?rev=433870&r1=433869&r2=433870&view=diff
==============================================================================
--- webservices/muse/trunk/modules/muse-core/src/org/apache/muse/core/AbstractFilePersistence.java (original)
+++ webservices/muse/trunk/modules/muse-core/src/org/apache/muse/core/AbstractFilePersistence.java Tue Aug 22 21:02:32 2006
@@ -34,10 +34,11 @@
/**
*
- * AbstractFilePersistence is a component that provides generic resource-to-file
- * utilities without specifying the format of the XML that goes into the files
- * for each resource type. It can be used to components that wish to save state
- * to disk on per-resource basis.
+ * AbstractFilePersistence is an abstract component that provides generic
+ * resource-state-to-file utilities without specifying the format of the XML
+ * that goes into the files. It can be used by resources or capabilities that
+ * wish to save state to disk and reload that state the next time the
+ * application is initialized.
*
* @author Dan Jemiolo (danj)
*
@@ -50,12 +51,23 @@
//
private static Messages _MESSAGES = MessagesFactory.get(AbstractFilePersistence.class);
- public static final String FILE_PREFIX = "resource-instance-";
-
+ //
+ // N -> EPR of resource whose state (or partial state) is being saved. here,
+ // N is a monotonically-increasing integer
+ //
private Map _fileNumbersByEPR = new HashMap();
+ //
+ // maps to the <persistence><location/></persistence> element in muse.xml.
+ // here, "location" is the directory that contains sub-directories with
+ // the state/partial-state of resource instances
+ //
private String _location = null;
+ //
+ // provides access to all of the resource instances that exist at runtime
+ // so we can add and compare to that set
+ //
private ResourceManager _manager = null;
//
@@ -63,9 +75,19 @@
//
private Map _parameters = null;
- protected abstract void createResourceFile(EndpointReference epr, Resource resource, File resourceFile)
- throws SoapFault;
-
+ /**
+ *
+ * Creates the proper file name for the given resource instance and then
+ * delegates creation of the file's contents to the abstract method of
+ * the same name.
+ *
+ * @param epr
+ * @param resource
+ *
+ * @see #getNextFileNumber()
+ * @see #createResourceFile(EndpointReference, Resource, File)
+ *
+ */
protected void createResourceFile(EndpointReference epr, Resource resource)
throws SoapFault
{
@@ -79,6 +101,49 @@
getFileNumbersByEPR().put(epr, new Integer(nextNumber));
}
+ /**
+ *
+ * This method should be overridden by concrete file-based persistence
+ * classes to create the given file and fill it with the appropriate
+ * XML content. Classes that are only interested in the serialization of
+ * a certain capability's data can use the Resource object to get access
+ * to said capability.
+ *
+ * @param epr
+ * The EPR that maps to the given Resource in the ResourceManager.
+ *
+ * @param resource
+ * The resource instance whose state is being persisted.
+ *
+ * @param resourceFile
+ * The File object that represents the yet-to-be-created XML file
+ * that will contain the content generated by this method. The
+ * implementation of this method must be sure to create the File
+ * on disk somehow.
+ *
+ * @throws SoapFault
+ * <ul>
+ * <li>If there is an error generating the proper content for the
+ * persistence file.</li>
+ * <li>If there is an I/O error while reading or writing to the
+ * file system.</li>
+ * </ul>
+ *
+ */
+ protected abstract void createResourceFile(EndpointReference epr, Resource resource, File resourceFile)
+ throws SoapFault;
+
+ /**
+ *
+ * Finds the file associated with the given resource EPR and removes it
+ * from the file system. This method should be called when a resource is
+ * destroyed (gone forever), but not when it is merely shutdown (because
+ * of server reboot, etc.).
+ *
+ * @param epr
+ * The EPR of the resource that has been permanently destroyed.
+ *
+ */
protected void destroyResourceFile(EndpointReference epr)
throws SoapFault
{
@@ -89,6 +154,11 @@
File resourceTypeDir = getResourceTypeDirectory(contextPath);
File[] results = resourceTypeDir.listFiles(filter);
+ //
+ // make sure we're not trying to delete state that doesn't exist,
+ // which won't cause an immediate error but may point to problems
+ // in the persistence impl
+ //
if (results.length == 0)
{
Object[] filler = { "\n\n" + epr };
@@ -99,6 +169,15 @@
getFileNumbersByEPR().remove(epr);
}
+ /**
+ *
+ * @param epr
+ *
+ * @return The last token after the last slash in the EPR's address. That
+ * is, for an EPR with address http://example.com/my-resource,
+ * the method returns 'my-resource'.
+ *
+ */
protected String getContextPath(EndpointReference epr)
{
String addressPath = epr.getAddress().getPath();
@@ -106,6 +185,14 @@
return addressPath.substring(slash + 1);
}
+ /**
+ *
+ * @param fileName
+ *
+ * @return The number at the end of the file name, before the suffix. That
+ * is, for a file named 'my-file-14.xml', the method returns 14.
+ *
+ */
protected Integer getFileNumber(String fileName)
{
int underscore = fileName.lastIndexOf('-');
@@ -119,6 +206,17 @@
return _fileNumbersByEPR;
}
+ /**
+ *
+ * @return The common string that will start all files created by the
+ * persistence implementation. This string will have the next
+ * file number appended to it in order to create unique file names.
+ *
+ * @see #getNextFileNumber()
+ *
+ */
+ protected abstract String getFilePrefix();
+
public String getInitializationParameter(String name)
{
return (String)getInitializationParameters().get(name);
@@ -129,21 +227,47 @@
return _parameters;
}
+ /**
+ *
+ * @param fileNumber
+ *
+ * @return A string of the following format: {file-prefix}{file-number}.xml
+ *
+ */
protected String getNextFileName(int fileNumber)
{
- return FILE_PREFIX + fileNumber + ".xml";
+ return getFilePrefix() + fileNumber + ".xml";
}
+ /**
+ *
+ * @return The next number that is available for creation of unique file
+ * names; this number is determined by taking the largest number
+ * currently used and incrementing it by one. The method does not
+ * attempt to reuse numbers in 'gaps' caused by deletions (that is,
+ * if numbers 1, 2, 5, and 6 are used, the method returns 7, not 3).
+ *
+ */
protected int getNextFileNumber()
{
if (getFileNumbersByEPR().isEmpty())
return 1;
+ //
+ // create a binary tree of numbers, pick the last one (= largest)
+ //
TreeSet sortedNumbers = new TreeSet(getFileNumbersByEPR().values());
Integer largest = (Integer)sortedNumbers.last();
return largest.intValue() + 1;
}
+ /**
+ *
+ * @return The File directory that was specified as the persistence location
+ * in muse.xml. The directory may not exist, so use File.exists()
+ * and/or File.mkdirs() to prevent I/O errors.
+ *
+ */
protected File getPersistenceDirectory()
{
String path = getPersistenceLocation();
@@ -154,12 +278,31 @@
File workingDir = getResourceManager().getEnvironment().getRealDirectory();
return new File(workingDir, path);
}
-
+
+ public String getPersistenceLocation()
+ {
+ return _location;
+ }
+
public ResourceManager getResourceManager()
{
return _manager;
}
+ /**
+ *
+ * @param contextPath
+ *
+ * @return Returns a directory for a given resource type, under the
+ * specified persistence location. The name of the directory
+ * is the context path provided. If the directory does not
+ * exist, this method will create it before returning the
+ * File object.
+ *
+ * @see #getPersistenceDirectory()
+ * @see File#mkdirs()
+ *
+ */
protected File getResourceTypeDirectory(String contextPath)
{
File dir = new File(getPersistenceDirectory(), contextPath);
@@ -170,6 +313,15 @@
return dir;
}
+ /**
+ *
+ * This implementation re-loads all saved instances of the resource types
+ * found in the ResourceManager. It delegates the actual reloading work
+ * to reloadResources(String, File).
+ *
+ * @see #reloadResources(String, File)
+ *
+ */
public void reload()
throws SoapFault
{
@@ -183,6 +335,41 @@
}
}
+ /**
+ *
+ * This method should be overridden by concrete file-based persistence
+ * classes to update a resource instance with the saved data from the
+ * XML fragment. The resource instance may be created by this method, or
+ * it may exist prior to invocation.
+ *
+ * @param contextPath
+ * The context path of the instance's resource type.
+ *
+ * @param resourceXML
+ * The persisted data that must be reloaded.
+ *
+ * @return The Resource instance whose state (or part of it) has been
+ * reloaded from XML. The Resource may have already existed
+ * prior to the method being called, and simply had one of its
+ * capabilities updated with saved data; it may also have been
+ * created by the method and initialized right before return.
+ *
+ */
+ protected abstract Resource reloadResource(String contextPath, Element resourceXML)
+ throws SoapFault;
+
+ /**
+ *
+ * This method finds all of the files in the resource type's persistence
+ * directory and reloads them one at a time. It delegates the reloading of
+ * individual resource instances to reloadResource(String, Element).
+ *
+ * @param contextPath
+ * @param resourceTypeDir
+ *
+ * @see #reloadResource(String, Element)
+ *
+ */
protected void reloadResources(String contextPath, File resourceTypeDir)
throws SoapFault
{
@@ -196,6 +383,7 @@
{
xmlDoc = XmlUtils.createDocument(resourceFiles[n]);
}
+
catch (Throwable error)
{
throw new RuntimeException(error.getMessage(), error);
@@ -210,21 +398,31 @@
getFileNumbersByEPR().put(resource.getEndpointReference(), fileNumber);
}
}
-
- protected abstract Resource reloadResource(String contextPath, Element resourceXML)
- throws SoapFault;
-
+
public void setInitializationParameters(Map parameters)
{
_parameters = parameters;
}
+
+ public void setPersistenceLocation(String location)
+ {
+ _location = location;
+ }
public void setResourceManager(ResourceManager manager)
{
_manager = manager;
}
- protected class FileNumberFilter implements FileFilter
+ /**
+ *
+ * FileNumberFilter finds files that end with a given number (excluding
+ * the file suffix).
+ *
+ * @author Dan Jemiolo (danj)
+ *
+ */
+ private class FileNumberFilter implements FileFilter
{
private Integer _fileNumber = null;
@@ -239,21 +437,19 @@
}
}
- protected class ResourceFileFilter implements FileFilter
+ /**
+ *
+ * ResourceFileFilter finds files that start with the value returned by
+ * getFilePrefix().
+ *
+ * @author Dan Jemiolo (danj)
+ *
+ */
+ private class ResourceFileFilter implements FileFilter
{
public boolean accept(File file)
{
- return file.getName().startsWith(FILE_PREFIX);
+ return file.getName().startsWith(getFilePrefix());
}
- }
-
- public String getPersistenceLocation()
- {
- return _location;
- }
-
- public void setPersistenceLocation(String location)
- {
- _location = location;
}
}
Modified: webservices/muse/trunk/modules/muse-core/src/org/apache/muse/core/AbstractResourceClient.java
URL: http://svn.apache.org/viewvc/webservices/muse/trunk/modules/muse-core/src/org/apache/muse/core/AbstractResourceClient.java?rev=433870&r1=433869&r2=433870&view=diff
==============================================================================
--- webservices/muse/trunk/modules/muse-core/src/org/apache/muse/core/AbstractResourceClient.java (original)
+++ webservices/muse/trunk/modules/muse-core/src/org/apache/muse/core/AbstractResourceClient.java Tue Aug 22 21:02:32 2006
@@ -34,10 +34,10 @@
/**
*
- * AbstractResourceProxy is a base class for resource proxies that are deployed
+ * AbstractResourceClient is a base class for resource clients that are deployed
* as doc-literal services using WS-Addressing. It can be used to send raw SOAP
* messages to web services, but it mainly serves as the foundation for more
- * concrete proxy classes.
+ * concrete client classes.
*
* @author Dan Jemiolo (danj)
*
@@ -56,7 +56,7 @@
private EndpointReference _destination = null;
//
- // The actual SOAP proxy used to send requests
+ // The actual SOAP client used to send requests
//
private SoapClient _soapClient = null;
@@ -196,7 +196,7 @@
*
* This is a convenience method that uses the given ProxyHandler to
* serialize the parameters (and deserialize the response) before
- * calling invoke(URI, Element).
+ * calling invoke(String, Element).
*
* @see #invoke(String, Element)
*
@@ -222,9 +222,8 @@
* to a resource.
* <br><br>
* The parameters are wrapped in a SOAP envelope and sent to the
- * destination using the proxy's SoapClient. If a JAX-RPC SOAPException
- * is thrown, it is wrapped in a RemoteException; if a SOAP Fault or
- * WS-BF BaseFault is returned, it is parsed and thrown as a BaseFault.
+ * destination using the proxy's SoapClient. If a SOAP Fault is returned,
+ * it is parsed and thrown as a SoapFault object.
*
* @return The SOAP Body from the response message, or null if there was
* no response.
@@ -233,10 +232,13 @@
public Element invoke(String action, Element soapBody)
throws SoapFault
{
- SoapClient soap = getSoapClient();
-
+ //
+ // SOAP bodies can technically have more than one element, so we
+ // have to wrap our data in an array
+ //
Element[] body = new Element[] { soapBody };
- Element[] response = soap.send(getSource(), getDestination(), action, body);
+
+ Element[] response = getSoapClient().send(getSource(), getDestination(), action, body);
//
// no response at all is still a valid response
Modified: webservices/muse/trunk/modules/muse-core/src/org/apache/muse/core/Capability.java
URL: http://svn.apache.org/viewvc/webservices/muse/trunk/modules/muse-core/src/org/apache/muse/core/Capability.java?rev=433870&r1=433869&r2=433870&view=diff
==============================================================================
--- webservices/muse/trunk/modules/muse-core/src/org/apache/muse/core/Capability.java (original)
+++ webservices/muse/trunk/modules/muse-core/src/org/apache/muse/core/Capability.java Tue Aug 22 21:02:32 2006
@@ -25,18 +25,16 @@
/**
*
* Capability is the atomic unit of functional definition for a resource
- * type. A capability instance should define a set of data and operations
+ * type. A capability class should define a set of data and operations
* that are closely-related, but do not necessarily make up the entire
- * definition of a resource interface. Users aggregate capabilities in
- * {@linkplain Resource Resource} instances, which take care of delegating
+ * definition of a resource interface. Users aggregate capabilities into
+ * a {@linkplain Resource Resource}, which takes care of delegating
* requests to the appropriate capabilities at runtime. Most users will
* only have to interact with the pluggable nature of Muse development
* through this interface and the <capability/> tag in muse.xml.
*
* @author Dan Jemiolo (danj)
*
- * @see org.apache.muse.core.descriptor.CapabilityDefinition
- *
*/
public interface Capability extends Initialization, InitializationParameters, Shutdown
@@ -44,7 +42,7 @@
/**
*
* @return All of the WS-A Action URIs for which the capability has
- * a MessageHandler
+ * a MessageHandler.
*
* @see #getMessageHandler(String)
*
@@ -59,6 +57,12 @@
*/
String getCapabilityURI();
+ /**
+ *
+ * @return The capability's access point for things such as the
+ * WS-Addressing context, file system resources, and more.
+ *
+ */
Environment getEnvironment();
/**
@@ -82,6 +86,12 @@
*/
MessageHandler getMessageHandler(String action);
+ /**
+ *
+ * @return The persistence mechanism for this capability, or null if none
+ * was defined.
+ *
+ */
Persistence getPersistence();
/**
Modified: webservices/muse/trunk/modules/muse-core/src/org/apache/muse/core/CapabilityContainer.java
URL: http://svn.apache.org/viewvc/webservices/muse/trunk/modules/muse-core/src/org/apache/muse/core/CapabilityContainer.java?rev=433870&r1=433869&r2=433870&view=diff
==============================================================================
--- webservices/muse/trunk/modules/muse-core/src/org/apache/muse/core/CapabilityContainer.java (original)
+++ webservices/muse/trunk/modules/muse-core/src/org/apache/muse/core/CapabilityContainer.java Tue Aug 22 21:02:32 2006
@@ -20,21 +20,47 @@
/**
*
- * CapabilityContainer is a sub-interface used by components that aggregate
- * capabilities into a larger interface. {@linkplain Resource Resource} is
- * an example of a simple capability container.
+ * CapabilityContainer is a an interface that defines the capability aggregation
+ * methods of {@linkplain Resource Resource}.
*
* @author Dan Jemiolo (danj)
*
*/
-public interface CapabilityContainer
+interface CapabilityContainer
{
+ /**
+ *
+ * Registers the given capability instance with the resource.
+ *
+ * @param capability
+ *
+ */
void addCapability(Capability capability);
-
+
+ /**
+ *
+ * @param capabilityURI
+ *
+ * @return The Capability associated with the given URI, or null if
+ * no such capability exists.
+ *
+ */
Capability getCapability(String capabilityURI);
-
+
+ /**
+ *
+ * @return The URIs of all of the capabilities added to the resource.
+ *
+ */
Collection getCapabilityURIs();
-
+
+ /**
+ *
+ * @param capabilityURI
+ *
+ * @return True, if getCapability(String) returns a non-null value.
+ *
+ */
boolean hasCapability(String capabilityURI);
}
Modified: webservices/muse/trunk/modules/muse-core/src/org/apache/muse/core/Environment.java
URL: http://svn.apache.org/viewvc/webservices/muse/trunk/modules/muse-core/src/org/apache/muse/core/Environment.java?rev=433870&r1=433869&r2=433870&view=diff
==============================================================================
--- webservices/muse/trunk/modules/muse-core/src/org/apache/muse/core/Environment.java (original)
+++ webservices/muse/trunk/modules/muse-core/src/org/apache/muse/core/Environment.java Tue Aug 22 21:02:32 2006
@@ -41,9 +41,7 @@
{
/**
*
- * Adds a piece of "context" for the current thread (request). This
- * context can be used by concrete Environments to provide access to
- * information that only the underlying platform can provide.
+ * Records the WS-Addressing data for the current request.
*
* @param context
* An object that can provide platform-specific information
@@ -63,18 +61,18 @@
/**
*
- * @return The ClassLoader used to load all classes and file system
- * resources.
+ * @return The WS-Addressing context for the current request.
*
*/
- ClassLoader getClassLoader();
+ MessageHeaders getAddressingContext();
/**
*
- * @return The context object for the current request.
+ * @return The ClassLoader used to load all classes and file system
+ * resources.
*
*/
- MessageHeaders getAddressingContext();
+ ClassLoader getClassLoader();
/**
*
@@ -152,17 +150,6 @@
*
*/
SoapClient getSoapClient();
-
- /**
- *
- * @return The EPR created from the WS-A headers specified in the current
- * request. This information should be retrievable from the
- * current context. If there is no target EPR (and thus, no
- * target resource) for the current request, then Muse will
- * not be able to delegate request handling to a resource instance.
- *
- */
- EndpointReference getTargetEPR();
/**
*
Modified: webservices/muse/trunk/modules/muse-core/src/org/apache/muse/core/Initialization.java
URL: http://svn.apache.org/viewvc/webservices/muse/trunk/modules/muse-core/src/org/apache/muse/core/Initialization.java?rev=433870&r1=433869&r2=433870&view=diff
==============================================================================
--- webservices/muse/trunk/modules/muse-core/src/org/apache/muse/core/Initialization.java (original)
+++ webservices/muse/trunk/modules/muse-core/src/org/apache/muse/core/Initialization.java Tue Aug 22 21:02:32 2006
@@ -20,7 +20,7 @@
/**
*
- * Initialization is a set of operations for sub-components that have a
+ * Initialization is a set of operations for components that have a
* distinct initialization state.
*
* @author Dan Jemiolo (danj)
Modified: webservices/muse/trunk/modules/muse-core/src/org/apache/muse/core/InitializationFailure.java
URL: http://svn.apache.org/viewvc/webservices/muse/trunk/modules/muse-core/src/org/apache/muse/core/InitializationFailure.java?rev=433870&r1=433869&r2=433870&view=diff
==============================================================================
--- webservices/muse/trunk/modules/muse-core/src/org/apache/muse/core/InitializationFailure.java (original)
+++ webservices/muse/trunk/modules/muse-core/src/org/apache/muse/core/InitializationFailure.java Tue Aug 22 21:02:32 2006
@@ -20,7 +20,7 @@
/**
*
- * InitializationFailure is a set of operations for sub-components that have
+ * InitializationFailure is a set of operations for components that have
* an initialization phase with distinct failure state.
*
* @author Dan Jemiolo (danj)
Modified: webservices/muse/trunk/modules/muse-core/src/org/apache/muse/core/InitializationParameters.java
URL: http://svn.apache.org/viewvc/webservices/muse/trunk/modules/muse-core/src/org/apache/muse/core/InitializationParameters.java?rev=433870&r1=433869&r2=433870&view=diff
==============================================================================
--- webservices/muse/trunk/modules/muse-core/src/org/apache/muse/core/InitializationParameters.java (original)
+++ webservices/muse/trunk/modules/muse-core/src/org/apache/muse/core/InitializationParameters.java Tue Aug 22 21:02:32 2006
@@ -42,7 +42,7 @@
/**
*
* @return The set of name-value pairs provided at initialization time.
- * The Map may be null.
+ * The Map may be empty.
*
*/
Map getInitializationParameters();
@@ -50,16 +50,12 @@
/**
*
* Allows the resource's creator to provide it with arbitrary name-value
- * settings that may be used during initialization. The way that these
+ * pairs that may be used during initialization. The way that these
* values are used and/or stored is an implementation detail, and there
* is no requirement that this feature be used - it is a generic way to
* specify deployment/initialization parameters. This method <b>should</b>
* be called before the resource is initialized.
- * <br><br>
- * Muse will load the <em>resource/instance/init-param</em> values in
- * muse.xml and use them to provide this Map. If the <em>init-param</em>
- * system is not used, you can still provide a Map with settings if you like.
- *
+ *
* @param parameters
* A simple set of name-value pairs - Map[String, String] - that
* contains initialization parameters for the resource.
Modified: webservices/muse/trunk/modules/muse-core/src/org/apache/muse/core/Messages.properties
URL: http://svn.apache.org/viewvc/webservices/muse/trunk/modules/muse-core/src/org/apache/muse/core/Messages.properties?rev=433870&r1=433869&r2=433870&view=diff
==============================================================================
--- webservices/muse/trunk/modules/muse-core/src/org/apache/muse/core/Messages.properties (original)
+++ webservices/muse/trunk/modules/muse-core/src/org/apache/muse/core/Messages.properties Tue Aug 22 21:02:32 2006
@@ -4,15 +4,14 @@
NoDataResource=The resource 'XXX' does not exist or is not in the classpath.
NullFactoryCollection=The Collection of ResourceDefinition references is null. An endpoint must have at least one resource type (factory) to instantiate.
NullResource=The owner resource is null.
-NoLogger=The router's log must be set with setLog() before it can be initialized (via initialize()). Make sure that a java.util.Logger reference is provided right after the router is instantiated.
+NoLogger=The resource's log must be set with setLog() before it can be initialized (via initialize()). Make sure that a java.util.Logger reference is provided right after the resource is instantiated.
ResourceInitialized=The resource at 'XXX' has been initialized.
EmptyFactoryCollection=The Collection of ResourceDefinition references is empty. An endpoint must have at least one resource type (factory) to instantiate.
-NoRequestContext=There was no context data for the current request. Every request for a web service operation should have access to context data that allows the runtime to find the target EPR (resource). Make sure your service code uses Environment.addContext().
-EndpointExists=There is already a resource type bound to the endpoint 'XXX'. You must provide a unique endpoint identifier for each resource type.
-NullEndpoint=There is a resource element in the muse.xml with a null endpoint element.
+ContextPathExists=There is already a resource type bound to the context path 'XXX'. You must provide a unique context path identifier for each resource type.
+NullContextPath=The context path is null.
NullProxyHandler=The ProxyHandler is null. How are we going to send requests?
NullSourceEPR=The proxy's source EPR is null. What is the caller's EPR?
-ActionNotSupported=The resource at 'XXX' does not expose an operation named 'XXX' through any of its capabilities.
+ActionNotSupported=The resource at 'XXX' does not expose an operation with the WS-Action 'XXX' through any of its capabilities.
ResourceDestroyed=The resource at 'XXX' has been destroyed.
NoFileForEPR=There is no XML file storing a router entry for the following EPR\: XXX
NullClassLoader=The ClassLoader is null. If you don't want to specify your own ClassLoader, use the default constructor, it will use the class' ClassLoader.
@@ -20,15 +19,25 @@
NullEnvironment=The Environment is null. A router must have a concrete Environment in order to discover information about the underlying system.
NoPersistenceLocation=If you use the FilePersistence class as your persistence mechansim, you must provide an initialization parameter (init-param) named 'persistence-location', which is a relative path to the directory storing the router entry files.
NullLogger=The Logger is null. A router must have a log, even if it is printing to the console.
-NullEndpointURL=The endpoint URL string is null. What is the resource type's unique endpoint value?
-EndpointNotFound=No resource definition was found for endpoint 'XXX'. The valid endpoints for this endpoint (as described in muse.xml) are\: XXX
-CapabilityInitialized=The resource at 'XXX' has initialized capability 'XXX'.
+ContextPathNotFound=No resource definition was found for context path 'XXX'. The valid endpoints for this endpoint (as described in muse.xml) are\: XXX
+CapabilityInitialized=The resource at 'XXX' has started initialization of capability 'XXX'.
+CapabilityInitializationComplete = The resource at 'XXX' has completed initialization of capability 'XXX.
ExistingResourceEPR=The unique EPR of this resource instance (object) has already been set - once a resource has an identifying EPR, it cannot be changed over its lifetime.
ResourceAlreadyDestroyed=The resource has already been destroyed. Make sure other resources do not hold stale references to it.
NoEnvironment=The router's Environment must be set with setEnvironment() before it can be initialized (via initialize()). Make sure that a org.apache.muse.core.Environment is provided right after the router is instantiated.
NullSoapClient=The SoapClient is null. How are we going to send requests?
CreateDocFailed=The XML document 'XXX' could not be loaded. The original error was\: XXX
NullCapability=The Capability is null.
-KeyNotFound=Could not find (and remove) the object associated with the following key: XXX
-KeyExists=The following key already exists in the container: XXX
-NullResourceKey=The resource key is null.
+ResourceEPRNotFound=Could not find the resource associated with the following EPR: XXX
+ResourceEPRExists=The following EPR already exists in the resource manager: XXX
+NullResourceEPR=The resource's EPR is null.
+DuplicateCapabilityURI = The resource type 'XXX' already has more than one capability defined by the URI 'XXX'. The capability URIs within a resource type definition must be unique.
+DuplicateAction = The resource type 'XXX' already handles the operation for WS-A Action 'XXX' with capability 'XXX'. The most likely cause of the error is that your WSDL has two operations with the same WS-A Action(s).
+NoResourceManager=The resource's ResourceManager must be set with setResourceManager() before it can be initialized (via initialize()). Make sure that a org.apache.muse.core.ResourceManager reference is provided right after the resource is instantiated.
+NoWsdlPath=The resource's WSDL path must be set with setWsdlPath() before it can be initialized (via initialize()). Make sure that the WSDL path is provided right after the resource is instantiated.
+NoWsdlPortType=The resource's WSDL portType must be set with setWsdlPortType() before it can be initialized (via initialize()). Make sure that the WSDL portType name is provided right after the resource is instantiated.
+NoWsdlPath=The resource's WSDL path must be set with setWsdlPath() before it can be initialized (via initialize()). Make sure that the WSDL path is provided right after the resource is instantiated.
+NullResourceManager=The ResourceManager reference is null.
+NullWsdlPath=The resource's WSDL path is null.
+NullWsdlPortType=The resource's WSDL portType name is null.
+NoContextPath=The resource's context path must be set with setContextPath() before it can be initialized (via initialize()). Make sure that the context path is provided right after the resource is instantiated.
Modified: webservices/muse/trunk/modules/muse-core/src/org/apache/muse/core/Persistence.java
URL: http://svn.apache.org/viewvc/webservices/muse/trunk/modules/muse-core/src/org/apache/muse/core/Persistence.java?rev=433870&r1=433869&r2=433870&view=diff
==============================================================================
--- webservices/muse/trunk/modules/muse-core/src/org/apache/muse/core/Persistence.java (original)
+++ webservices/muse/trunk/modules/muse-core/src/org/apache/muse/core/Persistence.java Tue Aug 22 21:02:32 2006
@@ -18,12 +18,55 @@
import org.apache.muse.ws.addressing.soap.SoapFault;
+/**
+ *
+ * Persistence is a mechanism used by resources and/or capabilities to save
+ * some or all of their state across application reboots. Concrete persistence
+ * classes provide the means for storage (file, database, etc.) as well as
+ * the logic to determine what content is stored. Note that this interface
+ * only describes how the persistence class should reload its data - not how
+ * it should initially find and save this data.
+ * <br><br>
+ * Peristence implementations are usually specified with the <em>persistence</em>
+ * element in muse.xml. This element allows users to specify the persistence
+ * location (the semantics of which are implementation-specific) and the concrete
+ * class that implements this interface.
+ *
+ * @author Dan Jemiolo (danj)
+ *
+ */
public interface Persistence extends InitializationParameters
{
+ /**
+ *
+ * @return The value specified in muse.xml under the <em>persistence</em>
+ * element. The semantics of this value are dependent on the type
+ * of storage used by the implementation class. As an example, a
+ * simple file-based persistence class might interpret the location
+ * to be the directory where files are stored; a database-oriented
+ * class might interpret it as the JNDI URI for the database.
+ *
+ */
String getPersistenceLocation();
+ /**
+ *
+ * @return The ResourceManager that stores all of the resource type
+ * definitions and all current resource instances.
+ *
+ */
ResourceManager getResourceManager();
+ /**
+ *
+ * Reads any data that was persisted by the class back into memory and
+ * provides it to the proper components (resource or capability). This
+ * method is normally called during the initialization of said components,
+ * before any requests are handled by the application.
+ *
+ * @throws SoapFault
+ *
+ */
void reload()
throws SoapFault;
Modified: webservices/muse/trunk/modules/muse-core/src/org/apache/muse/core/Resource.java
URL: http://svn.apache.org/viewvc/webservices/muse/trunk/modules/muse-core/src/org/apache/muse/core/Resource.java?rev=433870&r1=433869&r2=433870&view=diff
==============================================================================
--- webservices/muse/trunk/modules/muse-core/src/org/apache/muse/core/Resource.java (original)
+++ webservices/muse/trunk/modules/muse-core/src/org/apache/muse/core/Resource.java Tue Aug 22 21:02:32 2006
@@ -27,24 +27,32 @@
/**
*
* Resource is an aggregate of Capability objects, providing a common
- * host for them to share information and sub-components. It also acts
- * as the final stop in the request delegation process, taking method
- * invocation requests from the
+ * host for them to share information and sub-components. The
+ * {@linkplain CapabilityContainer CapabilityContainer} interface, while
+ * small, is the most important part of the Resource interface, for it
+ * describes Resource's primary role in the Muse framework.
+ * <br><br>
+ * This interface also acts as the final stop in the request delegation process,
+ * taking method invocation requests from the
* {@linkplain org.apache.muse.core.routing.ResourceRouter ResourceRouter}
* and passing them along to the appropriate Capability based on its
* knowledge of each Capability's supported operations. This allows the
* Capability classes to do their work in a way that is independent of
- * SOAP or request-handling or other plumbing.
+ * SOAP request-handling and other plumbing.
* <br><br>
* From a remote client perspective, Resource is the atomic unit of
* definition, since WSDL 1.1 does not allow resource interfaces to
* be broken down into distinct sub-interfaces (capabilities). However,
* from a server-side programming model perspective, Resource is not the
- * most granular level of resource definition.
+ * most granular level of resource definition - users should focus on creating
+ * {@linkplain Capability capabilities} and use Resource as a means of
+ * communicating between those capabilities.
*
* @author Dan Jemiolo (danj)
*
- * @see org.apache.muse.core.descriptor.ResourceDefinition
+ * @see CapabilityContainer
+ * @see Capability
+ * @see Capability#getResource()
*
*/
@@ -70,25 +78,30 @@
/**
*
- * @return The Muse Environment that is used to provide the resource
- * with access to the "outside world" (deployment information
- * and underlying platform).
+ * @return The resource's access point for things such as the
+ * WS-Addressing context, file system resources, and more.
*
*/
Environment getEnvironment();
/**
*
- * @return The Logger used to record resource-generated events.
+ * @return The JDK logger that writes to the Muse log file.
*
*/
Logger getLog();
+ /**
+ *
+ * @return The ResourceManager that stores all of the resource type
+ * definitions and all current resource instances.
+ *
+ */
ResourceManager getResourceManager();
/**
*
- * @return The WSDL that contains the resource's portType.
+ * @return The relative path of the WSDL file with the resource's portType.
*
*/
String getWsdlPath();
@@ -103,11 +116,13 @@
/**
*
* This is a generic method invocation mechanism that can be used to
- * delegate request handling to a specific method through a base class
- * reference (this class). This is intended to be used by code that is
- * handling external requests, and it may not allow the invocation of
- * all methods defined by the type. Internal clients should make normal
- * Java method calls with the actual method parameters.
+ * delegate request handling to a capability or some other component.
+ * It is intended to be used by code that is handling external requests,
+ * and it may not allow the invocation of all methods defined by the type.
+ * Internal clients should make 'normal' Java method calls with the actual
+ * method parameters; the getCapability(String) method provides access
+ * to the Capability objects that make up the resource type, all of which
+ * will have 'normal' Java methods for their operations.
*
* @param soapBody
* The parameters for the method, still in their SOAP Body form.
@@ -119,70 +134,17 @@
*/
Element invoke(Element soapBody);
- /**
- *
- * Provides the resource with the unique part of its SOAP endpoint URL.
- * This is specified at deployment time and can be used by the resource
- * to find its matching ResourceDefinition if needed. <b>This field must be
- * set before the resource can be initialized.</b>
- *
- * @param contextPath
- * The unique part of the SOAP endpoint URL that defines this
- * resource's type. Every resource type should have a unique
- * SOAP endpoint. This value should map to a <em>context-path</em>
- * value in muse.xml.
- *
- */
void setContextPath(String contextPath);
- /**
- *
- * Provides the resource with the unique EPR needed to distinguish
- * the resource from other instances of the same type. This method
- * can only be called once per resource object. <b>This field must
- * be set before the resource can be initialized.</b>
- *
- * @param epr
- *
- */
void setEndpointReference(EndpointReference epr);
- /**
- *
- * Provides the resource with the Muse Environment needed to access
- * deployment information and underlying platform features. <b>This field
- * must be set before the resource can be initialized.</b>
- *
- * @param environment
- *
- */
void setEnvironment(Environment environment);
- /**
- *
- * Provides the resource with the Logger it should use to record events.
- * <b>This field must be set before the resource can be initialized.</b>
- *
- * @param log
- *
- */
void setLog(Logger log);
void setResourceManager(ResourceManager manager);
- /**
- *
- * @param wsdlPath
- * The WSDL that contains the resource's portType.
- *
- */
void setWsdlPath(String wsdlPath);
- /**
- *
- * @param wsdlPortType
- * The WSDL portType that defines the resource.
- *
- */
void setWsdlPortType(QName wsdlPortType);
}
Modified: webservices/muse/trunk/modules/muse-core/src/org/apache/muse/core/ResourceManager.java
URL: http://svn.apache.org/viewvc/webservices/muse/trunk/modules/muse-core/src/org/apache/muse/core/ResourceManager.java?rev=433870&r1=433869&r2=433870&view=diff
==============================================================================
--- webservices/muse/trunk/modules/muse-core/src/org/apache/muse/core/ResourceManager.java (original)
+++ webservices/muse/trunk/modules/muse-core/src/org/apache/muse/core/ResourceManager.java Tue Aug 22 21:02:32 2006
@@ -23,17 +23,18 @@
import org.apache.muse.ws.addressing.soap.SoapFault;
/**
+ *
* ResourceManager defines the interface for creating and storing resources
* that can be targeted by other resources (internal and external to a
* Muse-derived application). The resources' endpoint references (EPRs) are
- * used to differentiate between resources in concrete implementations.
+ * used to differentiate between resources in concrete implementations. This
+ * is the <em>implied resource pattern</em> required by WS-Addressing.
* <br><br>
* Note that ResourceManager does not initiate any lifecycle events - the
- * add() operation does not create a resource, and the remove() operation
- * does not destroy a resource. Other components can use the create()
- * method to instantiate a resource and add() to make it visible to remote
- * clients, but the ResourceManager will not start this process as part of
- * its lifecycle.
+ * addResource() method does not create a resource, and the removeResource()
+ * method does not destroy a resource. Other components can use the
+ * createResource() method to instantiate a resource and addResource() to make
+ * it visible to remote clients.
*
* @author Dan Jemiolo (danj)
*
@@ -76,23 +77,51 @@
*
* @param definitions
* The ResourceDefinition objects that will be used to generate new
- * resource instances. There must be at least one factory in the
- * given array, because each application must define at least one
- * resource type.
+ * resource instances.
*
- * @see org.apache.muse.core.descriptor.DeploymentDescriptor#getResourceDefinitions()
- *
*/
void addResourceDefinitions(Collection definitions);
+ /**
+ *
+ * Finds the resource type definition associated with the given context
+ * path (defined in muse.xml), instantiates an instance of the resource
+ * class, and sets the basic values (EPR, initialization parameters, etc.)
+ * and Muse components (Environment, log file, etc.) that it needs to
+ * operate.
+ * <br><br>
+ * The Resource object returned by this method has <b>not</b> been initialized
+ * yet. Once the Resource.initialize() method has been called, the resource
+ * should be added to the ResourceManager with the addResource() method.
+ *
+ * @param contextPath
+ * The context path for the resource type that is to be instantiated.
+ * This value is specified with the <em>context-path</em> element in
+ * muse.xml.
+ *
+ * @return An instance of the resource class. It will have a proper EPR,
+ * all of its capabilities, and references to all of the basic
+ * Muse components (Environment, log file, etc.). Calling code may
+ * further modify the resource before calling initialize() and
+ * making it available to clients.
+ *
+ * @throws SoapFault
+ *
+ */
Resource createResource(String contextPath)
throws SoapFault;
+ /**
+ *
+ * @return The manager's access point for things such as the
+ * WS-Addressing context, file system resources, and more.
+ *
+ */
Environment getEnvironment();
/**
*
- * @return The number of resources stored by the manager.
+ * @return The number of resource instances stored by the manager.
*
*/
int getNumberOfResources();
@@ -102,7 +131,7 @@
* @param epr
* The unique EPR that is associated with the desired resource.
*
- * @return The resource associated with the given key, or null if no
+ * @return The resource associated with the given EPR, or null if no
* such resource exists.
*
*/
@@ -125,20 +154,25 @@
*/
String getResourceContextPath(Class capabilityClass);
- Collection getResourceContextPaths(Class capabilityClass);
-
/**
*
- * @return A collection containing all of the ResourceDefinition objects,
- * one for each resource type defined in the application's
- * deployment descriptor(s). The collection may be empty.
+ * @return A collection containing the context paths for all resource
+ * types specified in muse.xml. The collection may be empty.
*
*/
Collection getResourceContextPaths();
+
+ /**
+ *
+ * This method is just like getResourceContextPath(Class) except that
+ * it returns multiple endpoints that use the capability.
+ *
+ */
+ Collection getResourceContextPaths(Class capabilityClass);
/**
*
- * @return An iterator over a <b>copy</b> of the resource EPR collection.
+ * @return An iterator over the collection of resource EPRs.
*
*/
Iterator getResourceEPRs();
@@ -147,26 +181,33 @@
*
* @param contextPath
*
- * @return True if the resource type was specified with the use-router-persistence
- * flag set to 'true' in muse.xml.
+ * @return True if the resource type was specified with the
+ * <em>use-router-persistence</em> flag set to 'true' in muse.xml.
*
*/
boolean isUsingPersistence(String contextPath);
-
+
+ /**
+ *
+ * Stops the given listener from receiving notifications about the
+ * addition and removal of resource instances.
+ *
+ * @param listener
+ *
+ */
void removeListener(ResourceManagerListener listener);
/**
*
* Removes the EPR-resource pair from the manager. This does <b>not</b>
- * destroy the resource - it merely removes it from the external view.
- * This method should not require WS-RL support on the part of resources.
+ * destroy the resource - it merely removes it from the external view.
*
* @param epr
* The unique EPR that maps to the resource being removed.
*
* @throws SoapFault
* <ul>
- * <li>If the key does not map to a resource.</li>
+ * <li>If the EPR does not map to a resource.</li>
* </ul>
*
*/
Modified: webservices/muse/trunk/modules/muse-core/src/org/apache/muse/core/ResourceManagerListener.java
URL: http://svn.apache.org/viewvc/webservices/muse/trunk/modules/muse-core/src/org/apache/muse/core/ResourceManagerListener.java?rev=433870&r1=433869&r2=433870&view=diff
==============================================================================
--- webservices/muse/trunk/modules/muse-core/src/org/apache/muse/core/ResourceManagerListener.java (original)
+++ webservices/muse/trunk/modules/muse-core/src/org/apache/muse/core/ResourceManagerListener.java Tue Aug 22 21:02:32 2006
@@ -36,9 +36,35 @@
public interface ResourceManagerListener
{
+ /**
+ *
+ * @param epr
+ * The unique EPR that is being associated with the new resource.
+ * This value should always be used over Resource.getEndpointReference()
+ * because some applications may choose to map multiple EPRs to the
+ * same resource instance, and thus getEndpointReference() will not
+ * provide an accurate value.
+ *
+ * @param resource
+ * The resource instance being associated with the given EPR.
+ *
+ * @throws SoapFault
+ *
+ */
void resourceAdded(EndpointReference epr, Resource resource)
throws SoapFault;
+ /**
+ *
+ * @param epr
+ * The unique EPR of the resource that has been destroyed - the
+ * Resource object is not provided because it would most likely
+ * be in an inconsistent state. At this point, the resource has
+ * already been 'destroyed'.
+ *
+ * @throws SoapFault
+ *
+ */
void resourceRemoved(EndpointReference epr)
throws SoapFault;
}
Modified: webservices/muse/trunk/modules/muse-core/src/org/apache/muse/core/Shutdown.java
URL: http://svn.apache.org/viewvc/webservices/muse/trunk/modules/muse-core/src/org/apache/muse/core/Shutdown.java?rev=433870&r1=433869&r2=433870&view=diff
==============================================================================
--- webservices/muse/trunk/modules/muse-core/src/org/apache/muse/core/Shutdown.java (original)
+++ webservices/muse/trunk/modules/muse-core/src/org/apache/muse/core/Shutdown.java Tue Aug 22 21:02:32 2006
@@ -20,7 +20,7 @@
/**
*
- * Shutdown is a set of operations for sub-components that have a
+ * Shutdown is a set of operations for components that have a
* distinct shutdown state.
*
* @author Dan Jemiolo (danj)
Modified: webservices/muse/trunk/modules/muse-core/src/org/apache/muse/core/SimpleResource.java
URL: http://svn.apache.org/viewvc/webservices/muse/trunk/modules/muse-core/src/org/apache/muse/core/SimpleResource.java?rev=433870&r1=433869&r2=433870&view=diff
==============================================================================
--- webservices/muse/trunk/modules/muse-core/src/org/apache/muse/core/SimpleResource.java (original)
+++ webservices/muse/trunk/modules/muse-core/src/org/apache/muse/core/SimpleResource.java Tue Aug 22 21:02:32 2006
@@ -55,31 +55,23 @@
// Used to lookup all exception messages
//
private static Messages _MESSAGES = MessagesFactory.get(SimpleResource.class);
-
- private Map _capabilitiesByAction = new HashMap();
//
- // All of the manageability capabilities supported by this resource. The
- // capabilities are keyed by their URI.
+ // WS-A Action -> Capability that defines the operation for the action
//
- private Map _capabilitiesByURI = new LinkedHashMap();
+ private Map _capabilitiesByAction = new HashMap();
//
- // The unique part of the resource's endpoint URL - this maps to the
- // <endpoint/> declaration in the resource's deployment descriptor.
- // We can use this value to find all of the deployment info for the
- // resource's type.
+ // Unique capability URI -> Capability
//
+ private Map _capabilitiesByURI = new LinkedHashMap();
+
private String _contextPath = null;
- //
- // Our portal to the outside world - this allows us to get information
- // about the underlying system in a platform-independent way
- //
private Environment _environment = null;
//
- // The (unique) EPR for this resource instance
+ // The EPR for this resource instance
//
private EndpointReference _epr = null;
@@ -87,20 +79,14 @@
private boolean _hasBeenShutdown = false;
- //
- // Used to log all messages - all instances of a concrete class will
- // write to the same log file, but each will have a reference to the
- // Logger. This makes it easier to initialize the log file at runtime,
- // using names of classes that we do not yet know about.
- //
private Logger _log = null;
private ResourceManager _manager = null;
//
- // Configuration parameters from the deployment descriptor
+ // initialization parameters from the deployment descriptor
//
- private Map _parameters = null;
+ private Map _parameters = Collections.EMPTY_MAP;
private String _wsdlPath = null;
@@ -110,23 +96,46 @@
{
if (capability == null)
throw new RuntimeException(_MESSAGES.get("NullCapability"));
-
+
+ //
+ // the capability inherits some basic components from the resource
+ //
capability.setResource(this);
capability.setLog(getLog());
capability.setEnvironment(getEnvironment());
+
+ String uri = capability.getCapabilityURI();
- _capabilitiesByURI.put(capability.getCapabilityURI(), capability);
+ //
+ // make sure we don't already have this capability
+ //
+ if (_capabilitiesByURI.containsKey(uri))
+ {
+ Object[] filler = { getContextPath(), uri };
+ throw new RuntimeException(_MESSAGES.get("DuplicateCapabilityURI", filler));
+ }
+
+ _capabilitiesByURI.put(uri, capability);
Iterator i = capability.getActions().iterator();
- // FIXME: check for duplicates
while (i.hasNext())
- _capabilitiesByAction.put(i.next(), capability);
- }
-
- protected Capability getCapabilityForAction(String action)
- {
- return (Capability)_capabilitiesByAction.get(action);
+ {
+ String action = (String)i.next();
+
+ //
+ // make sure some other capability isn't already using this action
+ // URI for one of its operations
+ //
+ if (_capabilitiesByAction.containsKey(action))
+ {
+ Capability duplicate = (Capability)_capabilitiesByAction.get(action);
+ Object[] filler = { getContextPath(), action, duplicate.getCapabilityURI() };
+ throw new RuntimeException(_MESSAGES.get("DuplicateAction", filler));
+ }
+
+ _capabilitiesByAction.put(action, capability);
+ }
}
public final Capability getCapability(String capabilityURI)
@@ -134,6 +143,11 @@
return (Capability)_capabilitiesByURI.get(capabilityURI);
}
+ /**
+ *
+ * @return All of the WS-A Action URIs supported by this resource.
+ *
+ */
protected Collection getCapabilityActions()
{
return Collections.unmodifiableSet(_capabilitiesByAction.keySet());
@@ -141,6 +155,20 @@
/**
*
+ * @param action
+ * A WS-A Action URI.
+ *
+ * @return The Capability object with the method that maps to the
+ * given WS-A Action URI.
+ *
+ */
+ protected Capability getCapabilityForAction(String action)
+ {
+ return (Capability)_capabilitiesByAction.get(action);
+ }
+
+ /**
+ *
* @return A collection with all of the capabilities' URIs.
*
*/
@@ -218,8 +246,17 @@
if (getEnvironment() == null)
throw new IllegalStateException(_MESSAGES.get("NoEnvironment"));
- // FIXME: check for ResourceManager
- // FIXME: check for WSDL
+ if (getResourceManager() == null)
+ throw new IllegalStateException(_MESSAGES.get("NoResourceManager"));
+
+ if (getContextPath() == null)
+ throw new IllegalStateException(_MESSAGES.get("NoContextPath"));
+
+ if (getWsdlPath() == null)
+ throw new IllegalStateException(_MESSAGES.get("NoWSDLPath"));
+
+ if (getWsdlPortType() == null)
+ throw new IllegalStateException(_MESSAGES.get("NoWSDLPortType"));
initializeCapabilities();
@@ -233,12 +270,21 @@
_hasBeenInitialized = true;
}
+ /**
+ *
+ * This method can be overrided to provide additional capability
+ * initialization logic that applies generally to all capabilities.
+ * Capability-specific initialization logic should be provided by
+ * overriding Capability.initialize().
+ *
+ */
protected void initializeCapabilities()
throws SoapFault
{
- Iterator i = getCapabilityURIs().iterator();
- String context = getContextPath();
+ String contextPath = getContextPath();
Logger log = getLog();
+
+ Iterator i = getCapabilityURIs().iterator();
//
// first create and initialize() all capabilities
@@ -248,8 +294,8 @@
String nextURI = (String)i.next();
Capability next = getCapability(nextURI);
next.initialize();
-
- Object[] filler = { context, nextURI };
+
+ Object[] filler = { contextPath, nextURI };
log.fine(_MESSAGES.get("CapabilityInitialized", filler));
}
@@ -264,15 +310,23 @@
Capability next = getCapability(nextURI);
next.initializeCompleted();
- // FIXME: different message
+ Object[] filler = { contextPath, nextURI };
+ log.fine(_MESSAGES.get("CapabilityInitializationComplete", filler));
}
}
public Element invoke(Element soapBody)
{
+ //
+ // get WS-A action, which maps to a Capability's operation
+ //
MessageHeaders wsa = getEnvironment().getAddressingContext();
String action = wsa.getAction();
+ //
+ // get the capability that owns this operation so we can
+ // delegate the request
+ //
Capability capability = getCapabilityForAction(action);
if (capability == null)
@@ -317,6 +371,9 @@
Logger log = getLog();
+ //
+ // log the details of de-serialization and reflection
+ //
if (parameters != null)
LoggingUtils.logCall(log, method, parameters);
@@ -330,7 +387,7 @@
public final void setContextPath(String contextPath)
{
if (contextPath == null)
- throw new NullPointerException(_MESSAGES.get("NullEndpoint"));
+ throw new NullPointerException(_MESSAGES.get("NullContextPath"));
_contextPath = contextPath;
}
@@ -353,6 +410,9 @@
public final void setInitializationParameters(Map parameters)
{
+ if (parameters == null)
+ parameters = Collections.EMPTY_MAP;
+
_parameters = parameters;
}
@@ -366,16 +426,25 @@
public void setResourceManager(ResourceManager manager)
{
+ if (manager == null)
+ throw new NullPointerException(_MESSAGES.get("NullResourceManager"));
+
_manager = manager;
}
public final void setWsdlPath(String wsdlPath)
{
+ if (wsdlPath == null)
+ throw new NullPointerException(_MESSAGES.get("NullWsdlPath"));
+
_wsdlPath = wsdlPath;
}
public final void setWsdlPortType(QName wsdlPortType)
{
+ if (wsdlPortType == null)
+ throw new NullPointerException(_MESSAGES.get("NullWsdlPortType"));
+
_wsdlPortType = wsdlPortType;
}
Modified: webservices/muse/trunk/modules/muse-core/src/org/apache/muse/core/SimpleResourceManager.java
URL: http://svn.apache.org/viewvc/webservices/muse/trunk/modules/muse-core/src/org/apache/muse/core/SimpleResourceManager.java?rev=433870&r1=433869&r2=433870&view=diff
==============================================================================
--- webservices/muse/trunk/modules/muse-core/src/org/apache/muse/core/SimpleResourceManager.java (original)
+++ webservices/muse/trunk/modules/muse-core/src/org/apache/muse/core/SimpleResourceManager.java Tue Aug 22 21:02:32 2006
@@ -36,10 +36,10 @@
/**
*
- * SimpleResourceManager is Muse's default implementation of lifecycle
- * management and the implied resource pattern, as defined by
- * {@linkplain ResourceManager ResourceManager}. It keeps a simple
- * table that maps EPRs to Resource instances.
+ * SimpleResourceManager is Muse's default implementation of resource lifecycle
+ * management and the implied resource pattern. It maintains a simple table
+ * that maps EPRs to Resource objects. Each EPR that is added to the manager
+ * must be unique, but multiple EPRs may be mapped to the same Resource object.
*
* @author Dan Jemiolo (danj)
*
@@ -54,8 +54,8 @@
MessagesFactory.get(SimpleResourceManager.class);
//
- // Used to create all resource instances - there is one resource
- // definition per unique endpoint URL
+ // context path -> ResourceDefinition - all the data needed to
+ // properly instantiate each resource type in muse.xml
//
private Map _definitionsByPath = new LinkedHashMap();
@@ -64,7 +64,10 @@
private boolean _hasBeenInitialized = false;
private boolean _hasBeenShutdown = false;
-
+
+ //
+ // the ResourceManagerListeners, in the order they were added
+ //
private List _listeners = new LinkedList();
//
@@ -89,7 +92,7 @@
// the key already exists - not allowed!
//
if (_resources.containsKey(epr))
- throw new SoapFault(_MESSAGES.get("KeyExists", new Object[]{ epr }));
+ throw new SoapFault(_MESSAGES.get("ResourceEPRExists", new Object[]{ epr }));
_resources.put(epr, resource);
}
@@ -127,7 +130,7 @@
if (_definitionsByPath.containsKey(endpoint))
{
Object[] filler = { endpoint };
- throw new RuntimeException(_MESSAGES.get("EndpointExists", filler));
+ throw new RuntimeException(_MESSAGES.get("ContextPathExists", filler));
}
_definitionsByPath.put(endpoint, definition);
@@ -142,20 +145,20 @@
if (definition == null)
{
Object[] filler = { contextPath, _definitionsByPath.keySet() };
- throw new SoapFault(_MESSAGES.get("EndpointNotFound", filler));
+ throw new SoapFault(_MESSAGES.get("ContextPathNotFound", filler));
}
Resource resource = definition.newInstance();
resource.setResourceManager(this);
- fixLocalEPR(resource);
+ fixContextPath(resource); // HACK: see javadoc for fixContextPath()
return resource;
}
/**
*
- * This method addresses the fact that all new resources have
+ * HACK: This method addresses the fact that all new resources have
* EPRs with wsa:Addresses of the resource type being targeted
* by the current request. The Environment looks up the target
* EPR and uses that as the basis for new EPR. In cases where
@@ -170,8 +173,12 @@
* reflect its resource type.
*
*/
- private void fixLocalEPR(Resource resource)
+ private void fixContextPath(Resource resource)
{
+ //
+ // get the current EPR/Address, and find the part where the
+ // context path starts...
+ //
EndpointReference epr = resource.getEndpointReference();
String address = epr.getAddress().toString();
int slash = address.lastIndexOf('/');
@@ -179,6 +186,10 @@
StringBuffer buffer = new StringBuffer();
buffer.append(address.substring(0, slash));
+ //
+ // substitute the resource type's context path for the one
+ // that was on there originally
+ //
String contextPath = resource.getContextPath();
if (contextPath.charAt(0) != '/')
@@ -186,6 +197,9 @@
buffer.append(contextPath);
+ //
+ // re-set EPR address
+ //
URI addressWithProperEndpoint = URI.create(buffer.toString());
epr.setAddress(addressWithProperEndpoint);
}
@@ -195,6 +209,11 @@
return _environment;
}
+ /**
+ *
+ * @return A <em>copy</m> of the list of ResourceManagerListeners.
+ *
+ */
protected List getListeners()
{
return new LinkedList(_listeners);
@@ -208,7 +227,7 @@
public synchronized Resource getResource(EndpointReference epr)
{
if (epr == null)
- throw new NullPointerException(_MESSAGES.get("NullResourceKey"));
+ throw new NullPointerException(_MESSAGES.get("NullResourceEPR"));
//
// make sure that required property value is used during
@@ -282,7 +301,7 @@
protected ResourceDefinition getResourceDefinition(String contextPath)
{
if (contextPath == null)
- throw new NullPointerException(_MESSAGES.get("NullEndpointURL"));
+ throw new NullPointerException(_MESSAGES.get("NullContextPath"));
Iterator i = _definitionsByPath.keySet().iterator();
@@ -301,7 +320,13 @@
return null;
}
-
+
+ /**
+ *
+ * @return This implementation returns an iterator over a <b>copy</b> of the
+ * collection of resource EPRs.
+ *
+ */
public synchronized Iterator getResourceEPRs()
{
Set copy = new HashSet(_resources.keySet());
@@ -354,7 +379,7 @@
if (resource == null)
{
Object[] filler = { epr };
- throw new SoapFault(_MESSAGES.get("KeyNotFound", filler));
+ throw new SoapFault(_MESSAGES.get("ResourceEPRNotFound", filler));
}
}
@@ -392,7 +417,13 @@
_environment = environment;
}
-
+
+ /**
+ *
+ * This implementation loops through all existing resource instances
+ * and tells them to shutdown().
+ *
+ */
public void shutdown()
throws SoapFault
{
Modified: webservices/muse/trunk/modules/muse-core/src/org/apache/muse/core/descriptor/CapabilityDefinition.java
URL: http://svn.apache.org/viewvc/webservices/muse/trunk/modules/muse-core/src/org/apache/muse/core/descriptor/CapabilityDefinition.java?rev=433870&r1=433869&r2=433870&view=diff
==============================================================================
--- webservices/muse/trunk/modules/muse-core/src/org/apache/muse/core/descriptor/CapabilityDefinition.java (original)
+++ webservices/muse/trunk/modules/muse-core/src/org/apache/muse/core/descriptor/CapabilityDefinition.java Tue Aug 22 21:02:32 2006
@@ -27,8 +27,6 @@
/**
*
- * CapabilityDefinition is ...
- *
* @author Dan Jemiolo (danj)
*
*/
@@ -51,26 +49,6 @@
private String _uri = null;
- public Capability newInstance()
- {
- Class theClass = getImplementationClass();
-
- Capability capability = (Capability)ReflectUtils.newInstance(theClass);
- capability.setCapabilityURI(getURI());
- capability.setMessageHandlers(getMessageHandlers());
- capability.setInitializationParameters(getInitializationParameters());
-
- PersistenceDefinition persistenceDef = getPersistenceDefinition();
-
- if (persistenceDef != null)
- {
- Persistence persistence = persistenceDef.newInstance();
- capability.setPersistence(persistence);
- }
-
- return capability;
- }
-
public Class getImplementationClass()
{
return _implementationClass;
@@ -86,11 +64,36 @@
return _handlers;
}
+ public PersistenceDefinition getPersistenceDefinition()
+ {
+ return _persistence;
+ }
+
public String getURI()
{
return _uri;
}
+ public Capability newInstance()
+ {
+ Class theClass = getImplementationClass();
+
+ Capability capability = (Capability)ReflectUtils.newInstance(theClass);
+ capability.setCapabilityURI(getURI());
+ capability.setMessageHandlers(getMessageHandlers());
+ capability.setInitializationParameters(getInitializationParameters());
+
+ PersistenceDefinition persistenceDef = getPersistenceDefinition();
+
+ if (persistenceDef != null)
+ {
+ Persistence persistence = persistenceDef.newInstance();
+ capability.setPersistence(persistence);
+ }
+
+ return capability;
+ }
+
public void setImplementationClass(Class implementationClass)
{
//
@@ -115,19 +118,14 @@
{
_handlers = handlers;
}
-
- public void setURI(String uri)
- {
- _uri = uri;
- }
- public PersistenceDefinition getPersistenceDefinition()
+ public void setPersistenceDefinition(PersistenceDefinition persistence)
{
- return _persistence;
+ _persistence = persistence;
}
- public void setPersistenceDefinition(PersistenceDefinition persistence)
+ public void setURI(String uri)
{
- _persistence = persistence;
+ _uri = uri;
}
}
Modified: webservices/muse/trunk/modules/muse-core/src/org/apache/muse/core/descriptor/CapabilityDescriptor.java
URL: http://svn.apache.org/viewvc/webservices/muse/trunk/modules/muse-core/src/org/apache/muse/core/descriptor/CapabilityDescriptor.java?rev=433870&r1=433869&r2=433870&view=diff
==============================================================================
--- webservices/muse/trunk/modules/muse-core/src/org/apache/muse/core/descriptor/CapabilityDescriptor.java (original)
+++ webservices/muse/trunk/modules/muse-core/src/org/apache/muse/core/descriptor/CapabilityDescriptor.java Tue Aug 22 21:02:32 2006
@@ -23,8 +23,6 @@
/**
*
- * CapabilityDescriptor is ...
- *
* @author Dan Jemiolo (danj)
*
*/
---------------------------------------------------------------------
To unsubscribe, e-mail: muse-commits-unsubscribe@ws.apache.org
For additional commands, e-mail: muse-commits-help@ws.apache.org