Architectur of Amsterdam conf

Lets start by looking at the general structure of an Amsterdam deployment descriptor.

<application>
  <name/>

  <service>
    <name/>

    <content-map>
      <content-map-entry>
        <url/>    
	<mime/>
	<protocol/>
	<root-element/>
      </content-map-entry>
    </content-map>

    <get-service-invoker>
      <worker-queue>
	<worker-que-conf/>
      </worker-queue>
      <protocol-factory>
	<protocol-handler-factory>
	  <protocol-conf>
	    <conf/>
	  </protocol-conf>
	</protocol-handler-factory>
      </protocol-factory>
      <handler-strategy/>
      <cron>
	<cron-entry>
	  <schedule-at/>
	  <job/>
	</cron-entry>
      </cron>
    </get-service-invoker>

    <filters>
      <filter>
	<filter-conf/>
      </filter>
    </filters>
    <publisher/>
  </service>
</application>

	    

An Amsterdam deployment unit is an application. An application may consist of one or more service elements. Each such service is actually an individual channel. The application element just makes it possible to group several channels together.

A channel (from here on named service) should have a name:

	    <service>
	    <name>mychannel</name>
	    

Logically a service consists of three parts.

• The invocation layer. This is where messages get put into the system. The invocation layer may be a GET invoker, which fetches data, or a REC invoker, which received data.
• A chain of filter, which may check or alter data.
• A publisher, which marks the end of the chain, and should logically put the messages into some other system (a publisher may actually do nothing).

There is however also something called the ContentMap. A content map is a meta-configuration of the types of jobs that a service should do. A content map contains entries, which each describes the data for a particular work. The name attribute in the content-map-entry is an ID and may be used by other elements in the descriptor to reference that specific content-map-entry.

A content-map is required for get-based invoker service, but not for rec-based. If left out in a rec-base one content-map-entry will be automatically crated with the same name as the service it belongs to.

A content-map-entry holds a specific configuration for a data entity that is to be references inside the service configurations. The attribute name must be unique within the complete XML file.

Here is the content map created by genapp:

	  <content-map>
	     <content-map-entry name="mychannel">
	       <url>.</url>     
	       <mime>text/xml</mime>
	       <protocol>DIR</protocol>
	       <root-element></root-element>
	     </content-map-entry>
	   </content-map>
	    

The Service invoker

Almost all component in Amsterdam are pluggable. Normally you must therefore specify a className attribute for these components. Each type takes a class that either implements a certain interface or extends a base class of some type. Some element may instead reference an existing mbean. More on that further down.

A service contains either a get-service-invoker or a rec-service-invoker. A GET service must contain a worker-queue and a protocol-factory. The attribute className must point to a valid class that implements the org.backsource.amsterdam.service.service.ServiceInvoker interface.

For a REC service invoker it is possible to get it registered as an MBean, by specifying a full ObjectName as the name attribute. If a jndi-name attribute is given a proxy will also be bound in JNDI that is both locally and remotely available.

If a use-bean attribute is used together with a name attribute the invoker will register itself with that MBean. This feature is for example supported by the org.backsource.amsterdam.service.jboss.RecMBeanServiceInvoker.

Currently available invokers are: org.backsource.amsterdam.service.GETServiceInvoker, org.backsource.amsterdam.service.RECServiceInvoker and org.backsource.amsterdam.service.jboss.RecMBeanServiceInvoker

Here's how GET would look:

	    <get-service-invoker 
	       className="org.backsource.amsterdam.service.GETServiceInvoker">
	    

And here's how usage of an external MBean may look:

	    <rec-service-invoker
	    className="org.backsource.amsterdam.service.jboss.RecMBeanServiceInvoker"
	    name="amsterdam.channel:service=Service,name=jmsout"
	    use-bean="true"
	    />
	    

A service invoker may (or must depending on type) contain the following sub elements: worker-queue,protocol-factory,handler-strategy,and cron

A worker-queue represents an invocation strategy for the invoker. All work to be done by the invoker should go through the WorkerQueue. The attribute className must point to a valid class that implements the org.backsource.service.amsterdam.service.workerqueue.WorkerQueue interface. If the worker-queue-conf element is present the class must also implement the org.backsource.service.amsterdam.metadata.XmlConfigurable interface.

Here's an example:

	    <worker-queue 
	      className="org.backsource.amsterdam.service.workerqueue.ThreadPoolWorkerQueue">
	      <worker-que-conf>
	        <max-threads>2</max-threads>
	      </worker-que-conf>
	    </worker-queue>
	    
	    

A protocol-factory is a factory for all the protocols that a particular service supports. It consists of one or more entries of protocol-handler-factory, which each knows how to return handlers for a specific protocol. The name of the protocol is governed by the content map entry for the job entry in question. The className attribute must point to a valid class which implements the org.backsource.amsterdam.service.protocol.ProtocolFactory interface.

A protocol handler factory is a class that knows how to create protocol handlers. The attribute className must point to a valid class that implements the org.backsource.amsterdam.service.protocol.ProtocolHandlerFactory interface.

A protocol-handler-factory may either contain a protocol-conf, which consists of one or more conf elements, or a protocol-owns-config element which contains ANY XML data. It is then up to the protocol-handler-factory to implement the org.backsource.service.amsterdam.metadata.XmlConfigurable interface.

Here is a directory protocol handler config that will fetch files from the ${jboss.server.data.dir}/channels/simplejms/data/ directory. The trailing "/" is important.

	    <protocol-factory 
	      className="org.backsource.amsterdam.service.protocol.DefaultProtocolFactory">
	      <protocol-handler-factory 
		className="org.backsource.amsterdam.plugins.file.DirProtocolHandlerFactory">
		<protocol-conf>
		  <conf name="BaseUrl">${jboss.server.data.dir}/channels/simplejms/data/</conf>
		</protocol-conf>
	      </protocol-handler-factory>
	    </protocol-factory>
	    

A handler-strategy represents a strategy that will have the possibility to partake in the protocol handlers action. Its only valid for GET invokers. The className attribute must point to a valid class that implements the org.backsource.amsterdam.service.strategy.HandlerStrategy interface. The element may contain any XML markup, and if it does the HandlerStrategy must be able to interpret it itself by implementing the org.backsource.service.amsterdam.metadata.XmlConfigurable interface. A typical strategy for a GET invoker is a remove strategy that removes files when they have been processed. Other variants is strategies that caches id:s of handled messages and do not allow more invokes that one and so forth.

Here's a strategy that removes files through the directory handler.

	  <handler-strategy 
	    selector="*" 
	    className="org.backsource.amsterdam.service.strategy.SimpleRemoveStrategy">
	  </handler-strategy>
	    

The last element is the cron element. Its only valid for GET invokers. The cron element contains cron-jobs, which is used to configure a CronManager. The CronManager will invoke the ServiceInvoker with the current job. All GET invoker need one or more cron entries to get it to do any work. The schedule-at contains a cron expression and the job element must point to the name of a content map entry.

Here's a cron that will run the jmsin content map entry jobb trough its invoker once every minute.

	    <cron>
	      <cron-entry>
		<schedule-at>* * * * *</schedule-at>
	        <job nameref="jmsin"/>
	      </cron-entry>
	    </cron>
	    

And here is a complete invoker example:

	  <get-service-invoker className="org.backsource.amsterdam.service.GETServiceInvoker">
	    
	    <worker-queue className="org.backsource.amsterdam.service.workerqueue.ThreadPoolWorkerQueue">
	      <worker-que-conf>
		<max-threads>2</max-threads>
	      </worker-que-conf>
	    </worker-queue>
	    
	    <protocol-factory 
	      className="org.backsource.amsterdam.service.protocol.DefaultProtocolFactory">
	      <protocol-handler-factory 
		className="org.backsource.amsterdam.plugins.file.DirProtocolHandlerFactory">
		<protocol-conf>
		  <conf name="BaseUrl">${jboss.server.data.dir}/channels/simplejms/data/</conf>
		</protocol-conf>
	      </protocol-handler-factory>
	    </protocol-factory>
	    
	    <handler-strategy 
	      selector="*" 
	      className="org.backsource.amsterdam.service.strategy.SimpleRemoveStrategy"></handler-strategy>
	    <cron>
	      <cron-entry>
		<schedule-at>* * * * *</schedule-at>
		<job nameref="jmsin"/>
	      </cron-entry>
	    </cron>
	    
	  </get-service-invoker>
	    

Filters

The filters element contains zero or more filters, that the arriving message will be put through before beeing published.

A filter is a class that does something with the incoming message. The attribute className must point to a valid class that implements the org.backsource.amsterdam.service.filter.ServiceFilter interface. If the filter is an mbean it is possible to get it registered in the mbean server by specifying a name attribute. This must either be a logical name (such as xslfilter) or a complete JMX ObjectName.

If a use-bean attribute is used together with a name attribute, the className attribute will be ignored and all calles will be delegated to the mbean pointed at by the name attribute. A filter may contain a filter-conf or a filter-map.

A filter-conf element is a container for any configuration the filter needs. It may contain any valid XML markup. If it is added the filter class must be implementing the org.backsource.service.amsterdam.metadata.XmlConfigurable interface.

The filter-map element is a specialized configuration element for xsl handling. Entries in it map a content map entry to an XSL file. A filter-map-entry binds an XSL file to a particular ContentMapEntry; and zero or more parameters that may be used i the XSL. The attribute nameref must contain one or more names for specifics content-map-entry name.

Here's a filter with its own configuration:

	     <filter className="org.backsource.amsterdam.plugins.file.FileHandler">
	      <filter-conf>
		<directory>${jboss.server.data.dir}/channels/axis-demo/raw-backup</directory>
	      </filter-conf>
	    </filter>
	    

Here's a filter that exposes an mbean

	    <filter
	    className="org.backsource.amsterdam.service.filter.DummyFilter"
	    name="ettFilter"
	    />
	    

And here is one that uses an external MBean:

	    <filter
	    name="amsterdam.channel:service=Service,name=tre,filter=treFilter"
	    use-bean="true"
	    />
	    

Where the MBean would have been defined earlier in the jboss-service.xml file:

	    <mbean code="org.backsource.amsterdam.service.filter.DummyFilter"
	    name="amsterdam.channel:service=Service,name=tre,filter=treFilter"/>
	    

Publisher

A publisher is the last component in the chain. The attribute className should point to a valid class which implements the org.backsource.amsterdam.service.publisher.Publisher interface. If the publisher is an mbean it is possible to get it registered in the mbean server by specifying a name attribute. This must either be a logical name (such as jmspublisher) or a complete JMX ObjectName. If a use-bean attribute is used together with a name attribute, the className attribute will be ignored and all called will be delegate to the mbean pointed at by the name attribute.

The element may contain any XML markup, but if it does the class itself must be able to interpret it by implementing the org.backsource.service.amsterdam.metadata.XmlConfigurable interface.

Its important to note that a publisher must always be defined, but what it actually does is up to the implementation. A filter may therefore also "publish".

Here's an axis publisher.

	  <publisher
	    className="org.backsource.amsterdam.plugins.axis.AxisHandler">
	    <ws-url>http://localhost:8080/axis-demo/services/DeliverDocument</ws-url>
	    <ns>http://localhost:8080/axis-demo</ns>
	    <method>handleDocument</method>
	    <user>vv</user>
	    <password>vv</password>
	  </publisher>
	    

And here's a publisher that will also be exposed as an MBean:

	    <publisher
	    className="org.backsource.amsterdam.service.publisher.DummyPublisher"
	    name="amsterdam.channel:service=Service,name=tva,publisher=tvaPublisher"
	    />
	    

Descriptor example

And here is the complete jboss-service.xml file generated by genapp, that needs to be filled in:

     <application>
	<service>
	  <name>mychannel</name>
	  <content-map>
	    <content-map-entry name="@ID">
	      <url>.</url>     
	      <mime>text/xml</mime>
	      <protocol>DIR</protocol>
	      <root-element></root-element>
	    </content-map-entry>
	  </content-map>
	  
	  <get-service-invoker className="org.backsource.amsterdam.service.GETServiceInvoker">
	    
	    <worker-queue className="org.backsource.amsterdam.service.workerqueue.ThreadPoolWorkerQueue">
	      <worker-que-conf>
		<max-threads>2</max-threads>
	      </worker-que-conf>
	    </worker-queue>
	    
	    <protocol-factory 
	      className="org.backsource.amsterdam.service.protocol.DefaultProtocolFactory">
	      <protocol-handler-factory 
		className="org.backsource.amsterdam.plugins.file.DirProtocolHandlerFactory">
		<protocol-conf>
		  <conf name="BaseUrl">${jboss.server.data.dir}/channels/mychannel/</conf>
		</protocol-conf>
	      </protocol-handler-factory>
	    </protocol-factory>
	    
	    <handler-strategy 
	      selector="*" 
	      className="org.backsource.amsterdam.service.strategy.SimpleRemoveStrategy"></handler-strategy>
	    <cron>
	      <cron-entry>
		<schedule-at>* * * * *</schedule-at>
		<job nameref="mychannel"/>
	      </cron-entry>
	    </cron>
	    
	  </get-service-invoker>
	  <filters>
	    <filter 
	      className="org.backsource.amsterdam.service.filter.DummyFilter"/>
	  </filters>
	  <publisher
	    className="org.backsource.amsterdam.service.publisher.DummyPublisher">
	  </publisher>
	</service>
      </application>