Apache Muse - Create a Resource (Persistence)

You can create new instances of a resource type at design time by adding pre-determined endpoint references to the router's data store. This section describes the steps you must take to provide the EPRs for the resources you want to create at application startup.

The deployment descriptor overview covers the nature of the router and its persistence mechanism; Muse has a default implementation of router persistence based on the file system, and we will use that to explore design-time resource creation. In order to create resources at startup, we must first design their EPRs, then store them in files, and then modify muse.xml to notify the router of their existence. When the Muse application is started, it will create a new resource for each EPR we have specified before any SOAP requests are processed.

• Design the resource EPRs - We must decide what the EPRs of our resources are, and that means selecting the name-value pairs that make up the WS-A reference parameters. The address of the EPR is determined by the Muse engine, so we don't even have to provide that - we just need the reference parameters. Let's assume that we want to create three instances of a resource with context path application-server - the reference parameters might something like this:

  <wsa:ReferenceParameters xmlns:wsa="http://www.w3.org/2005/08/addressing">
    <myns:ServerName>server1</myns:ServerName>
</wsa:ReferenceParameters>

<wsa:ReferenceParameters xmlns:wsa="http://www.w3.org/2005/08/addressing">
    <myns:ServerName>server2</myns:ServerName>
</wsa:ReferenceParameters>

<wsa:ReferenceParameters xmlns:wsa="http://www.w3.org/2005/08/addressing">
    <myns:ServerName>server3</myns:ServerName>
</wsa:ReferenceParameters>



  Each of the parameter sets is unique - they all have the same parameter name (which is normal for instances of the same resource type) but their values are different. At runtime, capability implementation logic will be able to use these parameter values to determine which resource instance is being referenced.
  


• Store the EPRs in files - The reference parameters must be put in XML files. The files should be named resource-instance-N.xml, where N is a monotonically increasing integer. The file-based persistence mechanism relies on multiple files to store the router table entries instead of one big file out of performance considerations.
  Note

  It is not expected that the file-based system will be used to create and maintain large numbers of resources in IT systems; rather, it should be used to create resources whose existence is rather permanent and have a very static role. Examples of such resource types would be resource factories, service groups, or system monitors.
  An example XML file named resource-instance-1.xml might look like this:

  <?xml version="1.0"?>
<wsa:ReferenceParameters xmlns:wsa="http://www.w3.org/2005/08/addressing">
    <myns:ServerName>server1</myns:ServerName>
</wsa:ReferenceParameters>


  Thus, the mapping of the reference parameter collection to XML file content is very straightforward.
  


• Describe the persistence mechanism in muse.xml - In the muse.xml file, under the router element, we'll need to create the following entry:

  <persistence>
    <persistence-location>router-entries</persistence-location>
    <java-persistence-class>org.apache.muse.core.routing.RouterFilePersistence</java-persistence-class>
<persistence>


  The first value, persistence-location, tells us how to reference the persistence mechanism; this is a generic reference that may have different semantics depending on the type of persistence used, but in our file-based system, it is a simple directory name. The router files are stored in /router-entries. The second value, java-persistence-class, is the name of the class that implements the Muse router persistence API and will handle the serialization of router table entries (EPRs). In this example, we're providing Muse's file-based persistence class.
  


• Add the XML files to the proper location - The persistence location (a directory named router-entries) must go in the Muse application directory. For Axis2 users, this is under the following path: /WEB-INF/services/muse/router-entries. Once this directory is created, create a sub-directory whose name is the context path of your resource type; in our example, this would be /WEB-INF/services/muse/router-entries/application-server. Put the XML files in this directory.
  


• Enable persistence for the resource type - Participation in the router's persistence mechanism is voluntary. To enable persistence of a given resource type's EPRs, you must add the use-router-persistence attribute to the <resource-type/> element and set it to true (the default value is false).
  


• Start the application - The first time the SOAP engine receives a request for your Muse-based application, it will start the Muse service, which will in turn process your pre-created router entries. It will create and initialize as many resources as there are EPR files, and it will assign EPRs with the given set of reference parameters. If your resource's capabilities have initialization logic, it will be executed during Resource.initialize(). Only after all of the pre-created resources are ready will the first SOAP request be processed.