Introduction

This page contains a real production example of a block assembly and block .xinfo description based an extract from a B2B Enterprise Integration and Collaboration Platform developed by OSM

This example was originally a Mailing List response to a some user questions!

The orginal post was written by Stephen McConnell from OSM.

The example

First we start with a manifest file in a jar the contains a block. The manifest contains the declaration of the path to the block implementation. This path is also used to resolve the .xinfo file. In this case the .xinfo description will be located under org/apache/acme/hub/gateway/pki/PKIProcessServer.xinfo 

Manifest-Version: 1.0
Created-By: ACME Corporation

Name: org/apache/acme/hub/gateway/pki/PKIProcessServer.class
Avalon-Block: true

The .xinfo file contains a description of a reasonably simple block that serves as a factory for business processes that handle PKI certification requests: 

<?xml version="1.0"?>

<blockinfo>
<block>
    <version>1.0</version>
  </block>

  <services>
      <!--
      This block could be declaring several services that it supports.
      Unlike a Java interface, the service includes a version tag. So
      it's possible for a block to have several services with possibly
      different versions. If there are multiple services then just
      declare them with multiple service entries here. Phoenix will make
      sure that the class with the same name as the .xinfo file
      implements these interfaces (if it doesn't then Phoenix will
      terminate).
      -->
      <service name="org.apache.acme.hub.gateway.FactoryService"/>
  </services>

  <!--
  So far, we have the definition of a class that supports possibly
  multiple version interfaces. But things get much more interesting, when
  we think about the services that this block requires in order to function
  properly. That's partly handled by the dependencies element and partly by
  the assembly.xml file (which I'll explain later). In the following
  dependency example there are seven "service" dependencies (i.e. 7 versioned
  interface dependencies that must be fulfilled for this block to function.
  -->

  <dependencies>
      <!--
      Each dependency contains a declaration of a role name and a service
      interface and a version that can fulfil that role. The dependency
      does not say anything about where that service implementation should
      come from (that's the job the assembly.xml file). The role element
      is simply the label used in the implementation of your block configure
      method that distinguishes a particular instance of the service.
      -->
      <dependency>
          <role>GATEWAY</role>
          <service name="org.apache.acme.hub.gateway.GatewayContext"/>
      </dependency>

      <!--
      This dependency declaration simply states that in order to function,
      this block requires a <service/> (in this case a wrapper to a CORBA
      ORB version 2.4) and that the block implementation will lookup this
      service using the "ORB" keyword.
      -->
      <dependency>
          <role>ORB</role>
          <service name="org.apache.acme.hub.gateway.ORBService"
                   version="2.4"/>
      </dependency>

      <!--
      This dependency declares a requirement for a PSS (Persistent State
      Service) Storage Home.
      -->
      <dependency>
          <role>PSS</role>
          <service name="org.apache.acme.hub.gateway.ProcessorStorageHomeService"/>
      </dependency>

      <!--
      This dependency enables the block to establish a call-back to the
      block supplying the service. This block uses the Registry interface
      to publish a business process description to a higher level manager.
      -->
      <dependency>
          <role>REGISTRY</role>
          <service name="org.apache.acme.hub.gateway.Registry"/>
      </dependency>

      <!-- etc. -->
      <dependency>
          <role>DOMAIN</role>
          <service name="org.apache.acme.hub.gateway.DomainService"/>
      </dependency>
      <dependency>
          <role>RANDOM</role>
          <service name="org.apache.acme.hub.gateway.RandomService"/>
      </dependency>
      <dependency>
          <role>CLOCK</role>
          <service name="org.apache.acme.service.time.TimeService"/>
      </dependency>

  </dependencies>

</blockinfo>

Next is the block declaration (an extract from an assembly.xml file). This enables the declaration of WHERE the services are coming from. I.e. you may have a system with many blocks and even the potential for matching services available from more that one block. The class attribute provides the link to the .xinfo file and the implementation class. The name is used a key within the assembly.xml file when wiring things together. E.g. the provide element references a block by its name - and declares that the named block will serve as the provider of the service. The role attribute matches the role element in the .xinfo dependency declaration. 

<?xml version="1.0"?>

<assembly>

  <!-- other assembly information here -->

  <!-- Certification Request Processor Factory -->
  <block class="org.apache.acme.pki.process.CertificationRequestServer"
         name="certification" >
    <provide name="gateway" role="GATEWAY"/>
    <provide name="gateway" role="ORB"/>
    <provide name="gateway" role="PSS"/>
    <provide name="gateway" role="DOMAIN"/>
    <provide name="gateway" role="RANDOM"/>
    <provide name="pki" role="REGISTRY"/>
    <provide name="time" role="CLOCK"/>
  </block>

  <!-- more assembly information here -->

</assembly>
  • It forces structure and separation
  • It provides a way of managing possibly multiple versions of the same interface in a single environment
  • It enables explicit declaration of the source of service provision

For example you can have multiple blocks providing a TimeService. One of those blocks uses an external time reference while the others use a local time reference. The local time block declare dependencies on the external source time block and is periodically synchronised. In this example all of the TimeService services are exposing the same interface, same version (i.e. same service), but the decision as to which service is the provider to another can be explicitly controlled. While the time example is perhaps trivial, there are significant policy security implications related to service provider selection.