Implicitly Scoped Classes

The EOA-INF sub-directory is an optional directory. It holds classes and/or jars that are implicitly scoped to the deployment's classpath, i.e. due to their placement within the deployment, as opposed to being explicitly modeled as a scoped dependency . A detailed discussion regarding the different dependency types and how they affect the deployment's classpath is discussed within the dependency management section.

By convention, classes defined within the deployment project's src directory are compiled and assembled into a jar named classes.jar and which must be defined in the root of the EOA-INF sub-directory. Note that this was done, as opposed to listing the classes directly within the root of a 'classes' sub-directory, to shorten the length of the directory path. Repository artifact paths can be quite long and windows is still unable to handle paths longer than 255 chars.

The EOA-INF/lib sub-directory can be used to scope jars to the deployment classpath. Note that the preferred method for scoping a jar artifact is to define it as a scoped dependency within the deployment's POM, which is discussed below. If, however, your deployment requires a library that cannot be sourced from a public repository, this is where you'd put it.

Describing the Deployment

A deployment's contents are modeled, i.e. described, using a deployment descriptor . The descriptor must be located within the META-INF/eoa sub-directory and it must be named deployment.xml. The contents of the descriptor are specific to the type of deployment, i.e. dependent upon whether it's an extension deployment or a component deployment , both of which are discussed below.

Defining Dependencies

As depicted within the system structural diagram, deployments may define dependencies upon other deployments. A dependency definition implies that the extension, or components, defined within the deployment, depend upon the existence of an extension, or one or more components, defined within the referenced deployment in order to implement its behavior.

A deployment's dependencies are defined within the deployment's POM, which must be located, according to maven convention, within a sub-directory named according to the artifact's ID and organization. Note that this meta-data is added to the deployment artifact by maven when your deployment project is installed into a repository. Note also that your deployment project's structure is specific to your build system. If you're using maven, we've prepared a how to for you which walks you through setting up an EOA deployment project within the context of the maven build system.

The contents of the POM file and the means by which dependencies are defined within it is discussed within the dependency management section.

Extension Deployment Descriptor

The contents of the extension deployment are modeled, i.e. described, via a deployment descriptor, which, as mentioned above, must be located within the META-INF/eoa sub-directory and which must be named deployment.xml. Following is an example extension deployment descriptor.

<deployment xmlns="http://bluestemsoftware.org/specification/eoa/1.0/deployment">
  <provider>
    <factory>org.bluestemsoftware.open.eoa.ext.feature.jms.server.activemq.JMSServerFeatureFactoryImpl</factory>
  </provider>
</deployment>

The deployment descriptor contains the name of the class which provides the extension factory's behavior and which must implement an interface which is assignable from the interface ExtensionFactory.Provider which is defined by the EOA specification. A reference containing the schema for the extension deployment descriptor and sample usages can be found here.

Note that you, the application developer, will more than likely never have to develop an alakai extension . If you feel the need, however, we've provided a how to which walks you through this process and which describes the distinction between an extension factory and an extension factory provider.

Extension Deployment Context

The EOA specification explicitly models the context within which an extension deployment is deployed via the ExtensionFactoryContext class. If you're writing extensions , this class provides some pretty useful hooks into the middleware API, namely access to the extension deployment itself, access to the extension deployment's classloader, which is discussed within the deployment classloader section, and a convenience method which allows you to locate deployment resources.

Every EOA Extension maintains a reference to the ExtensionFactory that created it. The extension factory can be used to access the deployment context object which describes the context within which the factory was deployed, e.g.

...

    // use the extension to retrieve a reference to the factory that
    // created it
    
    ExtensionFactory extensionFactory = myExtension.getExtensionFactory();
    
    // every extension factory maintains a reference to a context
    // object which describes the context within which it was deployed
    
    ExtensionFactoryContext deploymentContext = extensionFactory.getFactoryContext();
    
    // we can then use the context object to retrieve the deployment
    // classloader or to retrieve a reference to the deployment itself.
    // note that before invoking any method defined on an extension factory,
    // or on an extension created by that factory, alakai switches the
    // thread's context classloader to the factory's deployment classloader
    
    DeploymentClassLoader deploymentClassLoader = deploymentContext.getClassLoader();
    ExtensionFactoryDeployment extensionDeployment = deploymentContext.getDeployment();
    
    // a convenience method is provided which allows you to locate
    // a resource which may be contained within the deployment, i.e.
    // as a file, located on the deployment's classpath or which may
    // be defined remotely (see the api for supported URL schemes.)
    
    Resource resource = deploymentContext.getResource("classpath:///schema/my.xsd");
    InputStream in = resource.getInputStream();
    
...    

The other useful thing about the extension deployment context object is that it can be used as a SAX2 entity resolver. As an example (assuming 'my-document' contains entity references):

...

  Resource resource = deploymentContext.getResource("classpath:///docs/my-document.xml");
  InputSource inputSource = new InputSource(resource.getInputStream());
  inputSource.setSystemId("classpath:///docs/my-document.xml");
  DocumentBuilderFactory factory = DocumentBuilderFactory.newInstance();
  factory.setNamespaceAware(true);
  DocumentBuilder documentBuilder = factory.newDocumentBuilder();
  documentBuilder.setEntityResolver(deploymentContext);
  Document myDocument = documentBuilder.parse(inputSource);

...  

Component Deployment Descriptor

The contents of the component deployment are modeled, i.e. described, via a deployment descriptor, which, as mentioned above, must be located within the META-INF/eoa sub-directory and which must be named deployment.xml. The structure of a component deployment descriptor is shown below. Note that a reference which contains the schema for the component deployment descriptor and sample usages can be found here.

<deployment xmlns="http://bluestemsoftware.org/specification/eoa/1.0/deployment">
  <components>
    <!-- static component definitions go here -->
  </components>
  <providers>
    <!-- runtime component definitions go here -->
  </providers>  
</deployment>

Component Deployment Context

The EOA specification explicitly models the context within which a component deployment is deployed via the ComponentContext class. When writing applications, this class provides some pretty useful hooks into the middleware API, namely access to the component deployment itself, access to the component deployment's classloader, which is discussed within the deployment classloader section, and a convenience method which allows you to locate deployment resources.

Every runtime component maintains a reference to the context object which describes the context within which it was deployed, e.g.

...

  private MyApplication myApplication;
  
  public void foo() {
      
    // within your applications you'll more than likely be using a
    // type specific application API, e.g. the spring application API,
    // which 'hides' the middleware API, i.e. the EOA specification
    // API. your application API should allow you to cast back into the
    // middleware as required, e.g. we cast myApplication to a type
    // specific EOA runtime engine component (see the spring application
    // example for more info regarding the spring application type)
    
    SpringEngine runtimeEngine = (SpringEngine)myApplication;
    
    // we then use it to retrieve a reference to the runtime application
    // component implemented by the runtime engine. note that the engine
    // is typically defined in a separate deployment
    
    SpringApplication runtimeApplication = runtimeEngine.getApplication();
    
    // retrieve the deployment context object which describes the
    // context within which the application component is deployed
    
    ComponentContext deploymentContext = runtimeApplication.getComponentContext();
    
    // you can then use the context object to retrieve the deployment
    // classloader or to retrieve a reference to the deployment itself.
    // note that before invoking any method defined on an application,
    // the engine that implements that application is responsible for
    // switching the thread's context classloader to an instance of
    // org.bluestemsoftware.specification.eoa.ApplicationClassLoader
    // which incorporates the deployment classloader into its
    // delegation hierarchy (this is discussed within the section on
    // class loading)
    
    DeploymentClassLoader deploymentClassLoader = deploymentContext.getClassLoader();
    ComponentDeployment componentDeployment = deploymentContext.getDeployment();
    
    // a convenience method is provided which allows you to locate
    // a resource which may be contained within the deployment, i.e.
    // as a file, located on the deployment's classpath or which may
    // be defined remotely (see the api for supported URL schemes.)
    
    Resource resource = deploymentContext.getResource("classpath:///schema/my.xsd");
    InputStream in = resource.getInputStream();
      
  }
    
...    

The other useful thing about the component deployment context object is that it can be used as a SAX2 entity resolver. As an example (assuming 'my-document' contains entity references):

...

  Resource resource = deploymentContext.getResource("classpath:///docs/my-document.xml");
  InputSource inputSource = new InputSource(resource.getInputStream());
  inputSource.setSystemId("classpath:///docs/my-document.xml");
  DocumentBuilderFactory factory = DocumentBuilderFactory.newInstance();
  factory.setNamespaceAware(true);
  DocumentBuilder documentBuilder = factory.newDocumentBuilder();
  documentBuilder.setEntityResolver(deploymentContext);
  Document myDocument = documentBuilder.parse(inputSource);

...  

Defining Static Components

Static component definitions are defined via one or more WSDL description(s), which can be in-lined within the optional components element. Note that the following example is intended to show you how to define static components . For more information on what differentiates a static component from a runtime component and the specifics regarding each component type, please refer to the components section.

<deployment xmlns="http://bluestemsoftware.org/specification/eoa/1.0/deployment">
  <components>
    <wsdl:description xmlns:wsdl="http://www.w3.org/ns/wsdl" targetNamespace="http://com.mycompany/eoa/om/1.0" xmlns:tns="http://com.mycompany/eoa/om/1.0">
      <wsdl:types>
        <xs:import namespace="http://mycompany.com/business/docs" xmlns:xs="http://www.w3.org/2001/XMLSchema" />
      </wsdl:types>
      <wsdl:interface name="OrderProcessor" xmlns:ns01="http://mycompany.com/business/docs">
        <wsdl:fault name="OutOfStockFault" element="ns01:OutOfStockFault" />
        <wsdl:fault name="OrderNotFoundFault" element="ns01:OrderNotFoundFault" />
        <wsdl:operation name="placeOrder" pattern="http://www.w3.org/ns/wsdl/in-out">
          <wsdl:input element="ns01:OrderRequest" xmlns:wsam="http://www.w3.org/2007/05/addressing/metadata" wsam:Action="urn:placeOrder" />
          <wsdl:output element="ns01:OrderResponse" xmlns:wsam="http://www.w3.org/2007/05/addressing/metadata" wsam:Action="urn:placeOrderResponse" />
          <wsdl:outfault ref="tns:OutOfStockFault" xmlns:wsam="http://www.w3.org/2007/05/addressing/metadata" wsam:Action="urn:placeOrderOutOfStockFault" />
        </wsdl:operation>
        <wsdl:operation name="getOrderStatus" pattern="http://www.w3.org/ns/wsdl/in-out" style="http://www.w3.org/ns/wsdl/style/iri" xmlns:wsdlx="http://www.w3.org/ns/wsdl-extensions" wsdlx:safe="true">
          <wsdl:input element="ns01:getOrderStatus" xmlns:wsam="http://www.w3.org/2007/05/addressing/metadata" wsam:Action="urn:getOrderStatus" />
          <wsdl:output element="ns01:OrderStatusResponse" xmlns:wsam="http://www.w3.org/2007/05/addressing/metadata" wsam:Action="urn:getOrderStatusResponse" />
          <wsdl:outfault ref="tns:OrderNotFoundFault" xmlns:wsam="http://www.w3.org/2007/05/addressing/metadata" wsam:Action="urn:getOrderStatusOrderNotFoundFault" />
        </wsdl:operation>
        <wsdl:operation name="completeOrder" pattern="http://www.w3.org/ns/wsdl/in-only">
          <wsdl:input element="ns01:ShippingConfirmation" xmlns:wsam="http://www.w3.org/2007/05/addressing/metadata" wsam:Action="urn:completeOrder" />
        </wsdl:operation>
      </wsdl:interface>
      <ext:application xmlns:ext="http://bluestemsoftware.org/specification/eoa/1.0/component/wsdl/ext" name="OrderManager">
        <ext:role name="http://mycompany.com/om/order/processor" interface="tns:OrderProcessor" />
      </ext:application>
    </wsdl:description>
  </components>
</deployment>

Defining Runtime Components

Runtime component definitions (which provide a static component's behavior) are defined within the optional providers element. Again, the following example is intended only to demonstrate how to define runtime components . For information regarding what a runtime component does, please see the runtime components section. The following example, which was borrowed from the spring application demo, and which was adapted to use the default application type, contains a runtime application definition.

<deployment xmlns="http://bluestemsoftware.org/specification/eoa/1.0/deployment">
  <providers>
    <application xmlns="http://bluestemsoftware.org/specification/eoa/ext/application/default/1.0" xmlns:tns="http://com.mycompany/eoa/om/1.0" name="tns:OrderManager">
      <partners>
        <applicationReference applicationName="tns:OrderManager">
          <roleReference roleName="http://mycompany.com/om/order/processor"/>
        </applicationReference>
        <applicationReference xmlns:ns="http://software.vendor.com/1.0" applicationName="ns:WarehouseManager">
          <roleReference roleName="http://mycompany.com/wm/order/processor"/>
        </applicationReference>
      </partners>
    </application>
  </providers>
</deployment>

As previously mentioned, components can reference components which are defined in a different deployment. This requires the definition of a dependency, which is the next topic of discussion.

Provided Dependency

A provided dependency is a dependency which is 'provided' by the system at runtime, i.e. as opposed to being resolved by the dependency manager (don't confuse this with the maven provided scope which implies something completely different.) A provided dependency, when defined within the context of the system POM, is used to configure the provided classloader, as described within the defining provided dependencies section. A provided dependency, when defined within the context of a deployment POM, is required so that you can compile and test your projects, i.e. it does not affect the provided classloader configuration. As defined by the interface MavenProvidedDependency, a provided dependency must specify scope system, type jar, and must define an absolute 'systemPath,' e.g.

<dependency>
  <groupId>org.bluestemsoftware.specification.eoa</groupId>
  <artifactId>specification-eoa</artifactId>
  <scope>system</scope>
  <version>0.8.0.0</version>
  <systemPath>${env.ALAKAI_HOME}/repository/org/bluestemsoftware/specification/eoa/specification-eoa/0.8.0.0/specification-eoa-0.8.0.0.jar</systemPath>
</dependency>

Again, the systemPath argument is only used by maven to compile your project. The path is not used by alakai when configuring the -classpath argument. This is instead defined within the alakai start-up scripts.

Shared Dependency

A shared dependency is used to define a constituent within the shared classpath which is managed by the shared classloader. A shared dependency can be defined within the system POM as well as within deployment POMs. Transitive dependencies upon which a shared dependency may depend are NOT processed. As defined by the interface MavenSharedDependency, a shared dependency must specify scope provided and type jar, e.g.

<dependency>
  <groupId>org.some.organization.some.application</groupId>
  <artifactId>shared-artifact-id</artifactId>
  <version>1.0</version>
  <scope>provided</scope>
</dependency>

Scoped Dependency

A scoped dependency is used to define a constituent within the deployment classpath which is managed by the deployment classloader. A scoped dependency can only be defined within a deployment POM. As defined by the interface MavenScopedDependency, a scoped dependency, must specify scope compile, type jar and must be flagged as optional, e.g.

<dependency>
  <groupId>org.some.organization.some.application</groupId>
  <artifactId>scoped-artifact-id</artifactId>
  <version>1.0</version>
  <scope>compile</scope>
  <optional>true</optional>
</dependency>

Note that when alakai processes a deployment's scoped dependencies it processes dependencies upon which each scoped dependency may depend transitively. To qualify as a transitive dependency, the referenced dependency must not be flagged as optional. All transitive scoped dependencies are also added to the deployment's classpath. When processing transitive scoped dependencies , the EOA specification prohibits circular references, i.e. if A depends on B who depends on C who depends on A, the associated deployment will fail to deploy.

Factory Dependency

A factory dependency is used to define a dependency within the system POM. Other than feature dependencies, which are a special type of factory dependency, deployments are not allowed to define factory dependencies. This restriction was designed into the EOA specification to mitigate the possibility of introducing rogue extensions into the system, i.e. by processing and installing them transitively. As defined by the interface MavenFactoryDependency, a factory dependency when defined within the system POM, must specify scope runtime and type eoa-factory, e.g.

<dependency>
  <groupId>org.some.organization.some.application</groupId>
  <artifactId>factory-artifact-id</artifactId>
  <version>1.0</version>
  <scope>runtime</scope>
  <type>eoa-factory</type>
</dependency>

Feature Dependency

A feature dependency may be defined within the system POM as well as within a deployment's POM. It implies that an extension or runtime component(s) defined within the deployment, require access to the feature created by the referenced factory in order to implement its/their behavior.

Note that feature dependencies are not typically defined within the system POM, i.e. alakai itself does not rely upon the existence of any features. An entry may, however, be required to force the loading of a specific version of a feature deployment which is discussed within the managing feature dependencies section. As defined by the interface MavenFeatureDependency, a feature dependency must specify scope runtime and type eoa-feature, e.g.

<dependency>
  <groupId>org.some.organization.some.application</groupId>
  <artifactId>feature-artifact-id</artifactId>
  <version>1.0</version>
  <scope>runtime</scope>
  <type>eoa-feature</type>
</dependency>

The EOA specification indicates that a feature can be flagged as required, the effect of which is discussed within the section on features. A feature dependency is, by default, considered to be required unless the dependency's optional element has a value of true.

Feature dependencies are transitively processed, i.e. the factory definitions for features upon which a feature dependency may depend (which are not flagged as optional) are loaded into the system. Note that feature enablement is a separate step, i.e. just the factory definitions are loaded. The features themselves are not instantiated and configured unless specifically enabled as discussed within the section on features. Note that when processing transitive feature dependencies, the EOA specification prohibits circular references, i.e. if A depends on B which depends on C which depends on A, the referencing deployment will fail to deploy.

Component Dependency

A component dependency may be defined within the system POM as well as within a component deployment's POM. Extension deployments cannot define component dependencies. A component dependency, within the context of a system POM, serves to deploy the component deployment as discussed within the deploying component deployments section. A component dependency defined within the context of a component deployment POM implies that one or more components which are defined within the component deployment reference one or more components defined within the referenced component deployment. This is explained within the component deployment dependencies section. As defined by the interface MavenComponentDependency, a component dependency must specify scope runtime and type eoa-component, e.g.

<dependency>
  <groupId>org.some.organization.some.application</groupId>
  <artifactId>component-artifact-id</artifactId>
  <version>1.0</version>
  <scope>runtime</scope>
  <type>eoa-component</type>
</dependency>

Alakai processes component dependencies transitively. A transitive component dependency is any component dependency referenced by a component dependency that is not marked as 'optional'. Some special rules regarding transitive component dependencies are indicated within the EOA specification which should be noted (the rationale behind these rules will make more sense once you've read the section on system dependencies and component deployment dependencies. )

• Shared dependencies defined by a transitive component dependency are not processed, i.e. they are not added to the shared classpath, which is managed by the shared classloader.
• Scoped dependencies defined by a transitive component dependency are not processed, i.e. they are not added to the deployment classpath, which is managed by the deployment classloader.
• Feature dependencies defined by a transitive component dependency are not processed, i.e. they are not added to the deployment classpath, which is managed by the deployment classloader.
• Other dependencies defined by a transitive component dependency are not processed.
• Circular component references are allowed. This is necessary to support the scenario where application's (defined in different deployments) define one another as partners. The concept of partners will be discussed within the components section.

Other Dependency

An other dependency is any top-level dependency, i.e. non-transitive dependency, with a type other than eoa-component, eoa-factory or eoa-feature and with runtime specified as the artifact scope, as defined by the class MavenOtherDependency, e.g.

<dependency>
  <groupId>org.some.organization.some.application</groupId>
  <artifactId>other-artifact-id</artifactId>
  <version>1.0</version>
  <scope>runtime</scope>
  <type>war</type>
</dependency>

This dependency type is silently ignored by alakai. It may, however, be used by extensions to implement their behavior. The SpringEngine, for example, supports dependencies of type war and will deploy the associated web application(s). Note also, that according to the EOA specification, the referenced dependency must be located within the root of the referencing deployment, i.e. the artifact is not resolved from a repository.

Configuring the System Classpath

The system POM can be used to configure the system classpath, which is managed by the system classloader.

Defining Provided Dependencies

Provided dependency entries are used by the alakai bootstrapper to configure the provided classloader. Note that the only dependency actually required by the alakai system is the provided dependency which defines the dependency on the EOA specification API artifact. The majority of a system's behavior is provided by extensions, which are defined as an extension to the core specification. An empty system model, as depicted below, without any extension or component dependencies, models a system instance exactly as defined by the core specification, i.e. sans any extended behavior.

<project xmlns="http://maven.apache.org/POM/4.0.0">
  <modelVersion>4.0.0</modelVersion>
  <groupId>com.mycompany.eoa.system</groupId>
  <artifactId>default</artifactId>
  <packaging>pom</packaging>
  <version>0.8.0.0</version>
  <name>default</name>
  <dependencies>
    <dependency>
      <groupId>org.bluestemsoftware.specification.eoa</groupId>
      <artifactId>specification-eoa</artifactId>
      <scope>system</scope>
      <version>0.8.0.0</version>
      <systemPath>${env.ALAKAI_HOME}/repository/org/bluestemsoftware/specification/eoa/specification-eoa/0.8.0.0/specification-eoa-0.8.0.0.jar</systemPath>
    </dependency>
  </dependencies>
</project>

Managing Shared Dependencies

Shared dependency entries are used to configure the shared classpath which is managed by the shared classloader. When two or more deployment artifacts deployed within the context of a system instance define the same shared dependency, alakai will, by default, load the latest version. To override this behavior, you must define a managed shared dependency within the system POM which specifies the desired version, e.g.

<project xmlns="http://maven.apache.org/POM/4.0.0">
  <modelVersion>4.0.0</modelVersion>
  <groupId>com.mycompany.eoa.system</groupId>
  <artifactId>default</artifactId>
  <packaging>pom</packaging>
  <version>1.0</version>
  <name>default</name>
  <dependencies>
    ...
    <dependency>
      <groupId>org.some.organization.some.application</groupId>
      <artifactId>shared-artifact-id</artifactId>
      <version>my.managed.version</version>
      <scope>provided</scope>
    </dependency>
    ...
  </dependencies>
</project>

Note that the alakai system does not, by itself, require that any specific artifacts be defined on the shared classpath, i.e. the shared classpath can be empty. This is solely defined by the deployments deployed within the context of the system.

Deploying Extension Deployments

The only way to deploy an extension factory artifact (other than feature factories which are deployed transitively) is to define it within your system POM, e.g.

<project xmlns="http://maven.apache.org/POM/4.0.0">
  <modelVersion>4.0.0</modelVersion>
  <groupId>com.mycompany.eoa.system</groupId>
  <artifactId>default</artifactId>
  <packaging>pom</packaging>
  <version>1.0</version>
  <name>default</name>
  <dependencies>
    ...
    <dependency>
      <groupId>org.some.organization.some.application</groupId>
      <artifactId>factory-artifact-id</artifactId>
      <version>1.0</version>
      <scope>runtime</scope>
      <type>eoa-factory</type>
    </dependency>
    ...
  </dependencies>
</project>

Managing Feature Dependencies

As mentioned within the section on feature dependencies, the system POM is not typically used to deploy feature factory definitions, i.e. they are loaded transitively. It may instead, however, be used to manage the deployment of a specific version of a feature implementation - the concept of feature implementations is discussed within the section on features. If more than one extension and/or component deployment defines a dependency on the same implementation of a specific feature, alakai will, by default, load the first version it encounters. To override this behavior, define a managed feature dependency within your system POM, e.g.

<project xmlns="http://maven.apache.org/POM/4.0.0">
  <modelVersion>4.0.0</modelVersion>
  <groupId>com.mycompany.eoa.system</groupId>
  <artifactId>default</artifactId>
  <packaging>pom</packaging>
  <version>1.0</version>
  <name>default</name>
  <dependencies>
    ...
    <dependency>
      <groupId>org.some.organization.some.application</groupId>
      <artifactId>feature-artifact-id</artifactId>
      <version>my.managed.version</version>
      <scope>runtime</scope>
      <type>eoa-feature</type>
    </dependency>
    ...
  </dependencies>
</project>

Note that, as discussed within the section on features, a feature must be explicitly enabled before it can be used. If no specific feature implementation is indicated within the server.xml file, and a definition for more than one implementation of the same feature type exists within the context of system, an arbitrary implementation will be enabled. To force alakai to load the managed version defined above, requires that you indicate its specific implementation within the server.xml file.

Deploying Component Deployments

To deploy a component deployment artifact, along with its transitive dependencies, requires that you define the component dependency within your system POM, e.g.

<project xmlns="http://maven.apache.org/POM/4.0.0">
  <modelVersion>4.0.0</modelVersion>
  <groupId>com.mycompany.eoa.system</groupId>
  <artifactId>default</artifactId>
  <packaging>pom</packaging>
  <version>1.0</version>
  <name>default</name>
  <dependencies>
    ...
    <dependency>
      <groupId>org.some.organization.some.application</groupId>
      <artifactId>component-artifact-id</artifactId>
      <version>1.0</version>
      <scope>runtime</scope>
      <type>eoa-component</type>
    </dependency>
    ...
  </dependencies>
</project>

Note that more than one version of the same component deployment can be deployed within the context of a system instance. The components defined within a deployment are identified by their qualified names as described within the section on components. The assumption here is that the target namespace(s) of the definitions within, e.g. version A of the deployment are different from those defined within version B of the deployment. As a best practice, the target namespace(s) defined within a deployment should incorporate the deployment version.

Extension Deployment Dependencies

An extension deployment's dependencies are defined within its POM file which is located within the deployment artifact as depicted below and as discussed within the section on deployment structure.

An extension deployment can define the following dependency types, the first three of which serve to configure the deployment classloader and the last two of which define dependencies on various artifacts required to implement the contained extension's behavior: provided dependencies, shared dependencies, scoped dependencies, feature dependencies and other dependencies, e.g.

<project xmlns="http://maven.apache.org/POM/4.0.0">
  <modelVersion>4.0.0</modelVersion>
  <groupId>com.mycompany.eoa.extensions</groupId>
  <artifactId>my-extension</artifactId>
  <name>my-extension</name>
  <version>1.0</version>
  <packaging>eoa-factory</packaging>
  <build>
    ...
  </build>
  <dependencies> 
    <!-- ************** provided dependencies ******************** -->
    <dependency>
      <groupId>org.bluestemsoftware.specification.eoa</groupId>
      <artifactId>specification-eoa</artifactId>
      <scope>system</scope>
      <version>0.8.0.0</version>
      <systemPath>${env.ALAKAI_HOME}/repository/org/bluestemsoftware/specification/eoa/specification-eoa/0.8.0.0/specification-eoa-0.8.0.0.jar</systemPath>
    </dependency>
    <!-- *************** shared dependencies ********************* -->
    <dependency>
      <groupId>org.some.organization.some.application</groupId>
      <artifactId>shared-artifact-id</artifactId>
      <version>1.0</version>
      <scope>provided</scope>
    </dependency>
    <!-- *************** scoped dependencies ********************* -->
    <dependency>
      <groupId>org.some.organization.some.application</groupId>
      <artifactId>scoped-artifact-id</artifactId>
      <version>1.0</version>
      <scope>compile</scope>
      <optional>true</optional>
    </dependency>
    <!-- ***************** feature dependencies ****************** -->
    <dependency>
      <groupId>org.some.organization.some.application</groupId>
      <artifactId>feature-artifact-id</artifactId>
      <version>1.0</version>
      <scope>runtime</scope>
      <type>eoa-feature</type>
    </dependency>
    <!-- ******************* other dependencies ******************** -->
    <dependency>
      <groupId>org.some.organization.some.application</groupId>
      <artifactId>my-admin-portlet</artifactId>
      <version>1.0</version>
      <scope>runtime</scope>
      <type>war</type>
    </dependency>
  </dependencies>
</project>

The dependencies defined by an extension deployment are modeled within the EOA specification by the ExtensionFactoryDependencies class.

Component Deployment Dependencies

A component deployment's dependencies are defined within its POM file which is located within the deployment artifact as depicted below and as discussed within the section on deployment structure.

A component deployment can define the following dependency types, the first three of which serve to configure the deployment classloader and the last three of which define dependencies on various artifacts required to implement the contained component's behavior: provided dependencies, shared dependencies, scoped dependencies, feature dependencies, component dependencies and other dependencies, e.g.

<project xmlns="http://maven.apache.org/POM/4.0.0">
  <modelVersion>4.0.0</modelVersion>
  <groupId>com.mycompany.eoa.components</groupId>
  <artifactId>my-components</artifactId>
  <name>my-components</name>
  <version>1.0</version>
  <packaging>eoa-component</packaging>
  <build>
    ...
  </build>
  <dependencies> 
    <!-- ************** provided dependencies ******************** -->
    <dependency>
      <groupId>org.bluestemsoftware.specification.eoa</groupId>
      <artifactId>specification-eoa</artifactId>
      <scope>system</scope>
      <version>0.8.0.0</version>
      <systemPath>${env.ALAKAI_HOME}/repository/org/bluestemsoftware/specification/eoa/specification-eoa/0.8.0.0/specification-eoa-0.8.0.0.jar</systemPath>
    </dependency>
    <!-- *************** shared dependencies ********************* -->
    <dependency>
      <groupId>org.some.organization.some.application</groupId>
      <artifactId>shared-artifact-id</artifactId>
      <version>1.0</version>
      <scope>provided</scope>
    </dependency>
    <!-- *************** scoped dependencies ********************** -->
    <dependency>
      <groupId>org.some.organization.some.application</groupId>
      <artifactId>scoped-artifact-id</artifactId>
      <version>1.0</version>
      <scope>compile</scope>
      <optional>true</optional>
    </dependency>
    <!-- ***************** feature dependencies ******************* -->
    <dependency>
      <groupId>org.some.organization.some.application</groupId>
      <artifactId>feature-artifact-id</artifactId>
      <version>1.0</version>
      <scope>runtime</scope>
      <type>eoa-feature</type>
    </dependency>
    <!-- ***************** component dependencies ***************** -->
    <dependency>
      <groupId>org.some.organization.some.application</groupId>
      <artifactId>component-artifact-id</artifactId>
      <version>1.0</version>
      <scope>runtime</scope>
      <type>eoa-component</type>
    </dependency>
    <!-- ******************* other dependencies ******************** -->
    <dependency>
      <groupId>org.some.organization.some.application</groupId>
      <artifactId>module-artifact-id</artifactId>
      <version>1.0</version>
      <scope>runtime</scope>
      <type>war</type>
    </dependency>
  </dependencies>
</project>

The dependencies defined by a component deployment are modeled within the EOA specification by the ComponentDependencies class.

Provided ClassLoader

The provided classloader is the parent classloader of all classloaders created by the system as documented within the AbstractClassLoader class, which is defined within the EOA specification. The parent of the provided classloader is the bootstrap classloader, which, if you're running on the Sun JVM, is the sun.misc.Launcher$AppClassLoader as depicted below.

The bootstrap classloader should have run.jar as its only constituent, which is configured within the alakai start-up scripts via the -classpath argument. We do not recommend modifying this setting. If your deployments require artifacts which are visible to one or more deployments, this should instead be accomplished by defining a shared dependency. Requests for classes/resources are first delegated to the parent classloader, i.e. the bootstrap classloader . If not found, the provided classloader attempts to load the class/resource from its set of provided dependencies, as depicted above. If still not found, a ClassNotFoundException is thrown.

Shared ClassLoader

The shared classloader is modeled within the EOA specification by the SharedClassLoader class. The shared classloader is 'shared' by all deployment classloaders and by the system classloader as well. Requests for classes/resources are first delegated to the parent classloader, i.e. the provided classloader. If not found, the shared classloader attempts to load the class/resource from its set of shared dependencies, as depicted below. If still not found, a ClassNotFoundException is thrown.

When configuring the shared classpath, if more than one deployment defines a shared dependency with the same organizationID and the same artifactID, alakai will, by default, load the latest version unless the dependency is managed by the system.

As a best practice, artifacts defined as shared dependencies should be restricted to specification libraries, i.e. libraries which contain primarily interfaces and abstract classes, e.g. the javax specification and EOA ext specification libraries. Libraries which contain implementation classes, should be scoped to the deployment classpath. Obviously there's no hard-and-fast rule as to what constitutes a specification library. Most organizations will, however, indicate their intent by qualifying the name of a specification library with the api suffix.

Note also, to avoid linkage errors, classes within a specification library must not reference classes within an implementation library, i.e. a library which is scoped to a deployment. The JVM uses the defining class loader to load a class when resolving referenced classes, i.e. the shared class loader would be asked to load the referenced class -> NoClassDefFoundError. If necessary, submit a feature request requesting that the authoring organization re-factor any specification artifact that violates the above guidelines.

System ClassLoader

The system classloader is modeled within the EOA specification by the SystemClassLoader class. The system classloader loads classes required by alakai to implement its 'core' behavior. When alakai is 'bootstrapped', the provided classloader is used to load and instantiate the SystemClassLoader. The system classloader effectively 'hides the system implementation' by scoping all jars defined within the 'alakai/lib' sub directory to its class repository as depicted below.

The jars within the 'alakai/lib' sub-directory are not visible to any other classloader. Requests for classes/resources are first delegated to the parent classloader, i.e. the provided classloader. If not found, the system classloader attempts to load the class/resource from its class repository. If not found, the shared classloader is consulted. And if still not found, a ClassNotFoundException is thrown.

Deployment ClassLoader

The deployment classloader is modeled within the EOA specification by the DeploymentClassLoader class. The deployment classloader loads classes required by extensions defined within the deployment in order to implement their behavior.

Classes scoped to a deployment are not visible to any other deployment, nor are they visible to the system. Requests for classes/resources are first delegated to the parent classloader, i.e. the provided classloader. If not found, the deployment classloader attempts to load the class/resource from its repository of scoped dependency artifacts. If not found, the shared classloader is consulted. And if still not found, a ClassNotFoundException is thrown.

Application ClassLoader

The application classloader is modeled within the EOA specification by the ApplicationClassLoader class. The application classloader loads classes which are required by an Application at runtime, i.e. an instance of runtime engine.

Requests for classes/resources are first delegated to the parent classloader, i.e. the provided classloader. If not found, the application classloader delegates to the deployment classloader for the extension factory used to create the runtime engine instance which implements the application. If not found, the application classloader delegates to the deployment classloader within which the runtime application was defined. Then, if not found, the shared classloader is consulted. And, if still not found, a ClassNotFoundException is thrown. Sounds complicated. The rationale behind this delegation path will, however, make more sense to you once you understand the distinction between a runtime engine and a runtime application.

Abstract Components

An abstract component, as its name implies, models an abstraction of a specific type of behavior, while a concrete component provides an implementation of that behavior. As an example, using the company metaphor depicted above, a job description is an abstract concept, whereas the employee that performs that job is a concrete implementation of that description - hopefully.

Types

The term types refers to schema types, i.e. element declarations, complex types and simple schema types. Schema types are, as you might expect, defined within schemas. The actual language used to model a schema within alakai is an extension to the core EOA specification. A list of the available schema extensions can be found on the extensions reference page. The examples used below use XML Schema. If you are unfamiliar with XML Schema, we recommend reading the w3c tutorial before proceeding.

Schema

Schemas are used within the context of an EOA system to declare schema properties, to declare schema fragments and to type message parts, e.g. a message's payload, which is the usage depicted within the company metaphor diagram. Schemas are defined within the EOA specification by the Schema class.

Schemas are deployed into the context of an EOA system by 'in-lining' them, or by importing and/or including them, within the WSDL types element of a component deployment. Alternatively, as depicted in the example below, schemas may also be defined within a deployment's <providers> element. Which, if your only deploying schemas, precludes having to come up with a bogus WSDL targetNamespace. The following example, which was borrowed from the spring application demo, shows some sample schema declarations. The types declared here will be referenced within other examples in the sections that follow.

<deployment xmlns="http://bluestemsoftware.org/specification/eoa/1.0/deployment">
  <providers>
    <xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema" elementFormDefault="qualified" targetNamespace="http://unused/imported/namespace">
    </xs:schema>
    <xs:schema id="MyProperties" xmlns:xs="http://www.w3.org/2001/XMLSchema" attributeFormDefault="qualified" elementFormDefault="qualified" targetNamespace="http://mycompany.com/business/docs" xmlns:tns="http://mycompany.com/business/docs">
      <xs:annotation xmlns:eoa="http://bluestemsoftware.org/specification/eoa/1.0/component/schema/ext">
        <xs:appinfo source="http://bluestemsoftware.org/specification/eoa/1.0">
          <eoa:property name="ZipCode" type="tns:tZipCode" />
          <eoa:property name="OrderNumber" type="tns:tOrderNumber" />
          <eoa:property name="Items" type="tns:tItemDetail" />
        </xs:appinfo>
      </xs:annotation>
      <xs:import namespace="http://unused/imported/namespace"/>
      <xs:complexType name="tItemDetail">
        <xs:sequence>
          <xs:element name="Item" minOccurs="0" maxOccurs="unbounded">
            <xs:complexType>
              <xs:attribute name="id" use="required" type="xs:NCName" />
              <xs:attribute name="quantity" use="required" type="xs:int" />
            </xs:complexType>
          </xs:element>
        </xs:sequence>
      </xs:complexType>
      <xs:simpleType name="tZipCode">
        <xs:restriction base="xs:string">
          <xs:pattern value="\d{5}|\d{0}" />
        </xs:restriction>
      </xs:simpleType>
      <xs:simpleType name="tOrderNumber">
        <xs:restriction base="xs:string">
          <xs:pattern value="\c{3}-\d{5}" />
        </xs:restriction>
      </xs:simpleType>
    </xs:schema>
    <xs:schema id="MyMessages" xmlns:xs="http://www.w3.org/2001/XMLSchema" attributeFormDefault="qualified" elementFormDefault="qualified" targetNamespace="http://mycompany.com/business/docs" xmlns:tns="http://mycompany.com/business/docs">
      <xs:include schemaLocation="#MyProperties" />
      <xs:element name="AvailabilityRequest">
        <xs:annotation xmlns:eoa="http://bluestemsoftware.org/specification/eoa/1.0/component/schema/ext">
          <xs:appinfo source="http://bluestemsoftware.org/specification/eoa/1.0">
            <eoa:fragment property="tns:ZipCode">
              <eoa:query>/tns:AvailabilityRequest/tns:ZipCode</eoa:query>
            </eoa:fragment>
            <eoa:fragment property="tns:Items">
              <eoa:query>/tns:AvailabilityRequest/tns:Items</eoa:query>
            </eoa:fragment>
          </xs:appinfo>
        </xs:annotation>
        <xs:complexType>
          <xs:sequence>
            <xs:element name="ZipCode" type="tns:tZipCode" />
            <xs:element name="Items" type="tns:tItemDetail" />
          </xs:sequence>
        </xs:complexType>
      </xs:element>
      <xs:element name="AvailabilityResponse">
        <xs:annotation xmlns:eoa="http://bluestemsoftware.org/specification/eoa/1.0/component/schema/ext">
          <xs:appinfo source="http://bluestemsoftware.org/specification/eoa/1.0">
            <eoa:fragment property="tns:OrderNumber">
              <eoa:query>/tns:AvailabilityResponse/@orderNumber</eoa:query>
            </eoa:fragment>
          </xs:appinfo>
        </xs:annotation>
        <xs:complexType>
          <xs:sequence>
            <xs:element name="ShippingCost" type="xs:string" />
          </xs:sequence>
          <xs:attribute name="orderNumber" type="tns:tOrderNumber" />
        </xs:complexType>
      </xs:element>
      <xs:element name="OutOfStockFault">
        <xs:annotation xmlns:eoa="http://bluestemsoftware.org/specification/eoa/1.0/component/schema/ext">
          <xs:appinfo source="http://bluestemsoftware.org/specification/eoa/1.0">
            <eoa:fragment property="tns:Items">
              <eoa:query>/tns:OutOfStockFault/tns:Items</eoa:query>
            </eoa:fragment>
          </xs:appinfo>
        </xs:annotation>
        <xs:complexType>
          <xs:sequence>
            <xs:element name="Items" type="tns:tItemDetail" />
          </xs:sequence>
        </xs:complexType>
      </xs:element>
      <xs:element name="ScheduleOrderRequest">
        <xs:annotation xmlns:eoa="http://bluestemsoftware.org/specification/eoa/1.0/component/schema/ext">
          <xs:appinfo source="http://bluestemsoftware.org/specification/eoa/1.0">
            <eoa:fragment property="tns:OrderNumber">
              <eoa:query>/tns:ScheduleOrderRequest/@orderNumber</eoa:query>
            </eoa:fragment>
          </xs:appinfo>
        </xs:annotation>
        <xs:complexType>
          <xs:attribute name="orderNumber" type="tns:tOrderNumber" />
        </xs:complexType>
      </xs:element>
      <xs:element name="ScheduleOrderResponse">
        <xs:annotation xmlns:eoa="http://bluestemsoftware.org/specification/eoa/1.0/component/schema/ext">
          <xs:appinfo source="http://bluestemsoftware.org/specification/eoa/1.0">
            <eoa:fragment property="tns:OrderNumber">
              <eoa:query>/tns:ScheduleOrderResponse/@orderNumber</eoa:query>
            </eoa:fragment>
          </xs:appinfo>
        </xs:annotation>
        <xs:complexType>
          <xs:attribute name="orderNumber" type="tns:tOrderNumber" />
          <xs:attribute name="estimatedShipDate" />
        </xs:complexType>
      </xs:element>
      <xs:element name="getOrderStatus">
        <xs:annotation xmlns:eoa="http://bluestemsoftware.org/specification/eoa/1.0/component/schema/ext">
          <xs:appinfo source="http://bluestemsoftware.org/specification/eoa/1.0">
            <eoa:fragment property="tns:OrderNumber">
              <eoa:query>/tns:getOrderStatus/tns:OrderNumber</eoa:query>
            </eoa:fragment>
          </xs:appinfo>
        </xs:annotation>
        <xs:complexType>
          <xs:sequence>
            <xs:element name="OrderNumber" type="tns:tOrderNumber" />
          </xs:sequence>
        </xs:complexType>
      </xs:element>
      <xs:element name="OrderStatusResponse">
        <xs:annotation xmlns:eoa="http://bluestemsoftware.org/specification/eoa/1.0/component/schema/ext">
          <xs:appinfo source="http://bluestemsoftware.org/specification/eoa/1.0">
            <eoa:fragment property="tns:OrderNumber">
              <eoa:query>/tns:OrderStatusResponse/@orderNumber</eoa:query>
            </eoa:fragment>
          </xs:appinfo>
        </xs:annotation>
        <xs:complexType>
          <xs:attribute name="orderNumber" type="tns:tOrderNumber" />
          <xs:attribute name="status" />
        </xs:complexType>
      </xs:element>
    </xs:schema>
  </providers>
</deployment>

Once deployed, schemas, which are root components, can be retrieved by qualified name. The qualified name is formed using the schema's target namespace as the namespace uri and the value of the schema id attribute as the local name. In the example above, the qualified names would be:

• {http://unused/imported/namespace}
• {http://mycompany.com/business/docs}MyProperties
• {http://mycompany.com/business/docs}MyMessages

... where the schema's targetNamespace represents the namespace URI and the schema ID serves as the local name. If a schema has no ID, which is the common case, then the local name is the empty string, i.e. as demonstrated by the first name in the list.

Remember that a schema component is static, i.e. it provides no additional behavior beyond that defined at 'compile-time.' You can use it to view a type declaration, a fragment, etc ... but you can't use it to, e.g. validate a document. This functionality is provided by a runtime schema component. The following example demonstrates how to look-up the MyMessages schema defined above and retrieve its runtime counterpart (please refer to the runtime schema section for a validation example.)

...

  // retrieve the schema by qualified name
  QName schemaName = new QName("http://mycompany.com/business/docs","MyMessages");
  Schema schema = SystemContext.getContext().getSystem().getSchema(schemaName);
  
  // retrieve its runtime provider
  SchemaDocument runtimeSchema = schema.getRuntimeProvider();

...

Schema References

Schemas may reference other schemas which are deployed within the same deployment, or within other deployments, by using the referenced component's fragment identifier, which in some cases is implied. A schema fragment identifier uses the following format:

targetNamespace#eoa.schema(schemaID)

In the example above, the MyProperties schema imports the unused namespace schema (which was added just to demonstrate this point) via an import with no location attribute. When no location attribute is supplied, it is implied by alakai to be the fully qualified fragment identifier of the referenced schema, which could have been explicitly specified as follows (note that the second pound sign must be escaped such that it qualifies as a legal URI fragment.)

<xs:import namespace="http://unused/imported/namespace" schemaLocation="#http://unused/imported/namespace%23eoa.schema()"/>

Now, lets assume that we want to reference the MyMessages schema defined in the example above from within another schema. Because two schemas share the same targetNamespace, our import must be specific, i.e. we must explicitly specify the pointer part of the fragment identifier (the rest is implied,) e.g.

<xs:schema targetNamespace="http://foo" xmlns:xs="http://www.w3.org/2001/XMLSchema">
  <xs:import namespace="http://mycompany.com/business/docs" schemaLocation="#MyMessages"/>
</xs:schema>

Note that the targetNamespace part of the fragment identifier is implied as the value of the namespace attribute, i.e. the fully qualified fragment identifier is implied to be:

http://mycompany.com/business/docs#eoa.schema(MyMessages)

When you're defining an include, the targetNamespace part of the fragment identifier, is implied to be the targetNamespace of the parent schema, i.e. as demonstrated in the example above, the MyMessages schema includes the MyProperties schema by specifying just the pointer part, e.g.

<xs:schema id="MyMessages" xmlns:xs="http://www.w3.org/2001/XMLSchema" attributeFormDefault="qualified" elementFormDefault="qualified" targetNamespace="http://mycompany.com/business/docs" xmlns:tns="http://mycompany.com/business/docs">
  <xs:include schemaLocation="#MyProperties" />
</xs:schema>

Schema Components

The EOA specification uses the term schema component to refer to to both an element declaration and a schema type as defined within the context of a schema. It is modeled within the specification by the SchemaComponent class. The only additional thing to note here is that all of the 'built-in' XML schema simple types are automatically declared by the system, e.g. xs:string, xs:int, etc ... If you need more guidance in regards to declaring element declarations, complex types and/or simple schema types, as demonstrated in the example above, please refer to the w3c tutorial.

Schema Properties

Schema properties are a construct defined by the EOA specification as modeled by the SchemaProperty class. A schema property allows you to define an 'alias' for a schema component. As indicated within the specification, the alias should be semanticaly significant from the name of the type it aliases. In the example above, properties are defined for three, hypothetical 'standardized types' - ZipCode, OrderNumber, and Items. As a best practice these should have been defined within a separate target namespace, i.e to distinguish them from the schemas used to define the message payloads.

<xs:schema targetNamespace="http://foo" elementFormDefault="qualified" xmlns:xs="http://www.w3.org/2001/XMLSchema">
  <xs:annotation xmlns:eoa="http://bluestemsoftware.org/specification/eoa/1.0/component/schema/ext">
    <xs:appinfo source="http://bluestemsoftware.org/specification/eoa/1.0">
      <eoa:property name="MyProperty" type="xs:string" />
    </xs:appinfo>
  </xs:annotation> 
</xs:schema>  

Because schema properties are a construct defined by the EOA specification and because XML Schema is not directly extensible, i.e. you can't define new xml schema element types, we must use the xs:annotation feature to declare our schema properties as depicted above. Schema properties must be defined as a 'top-level' annotation, i.e. which annotates the schema itself, and they must be be defined within an <xs:appinfo> element which defines a source attribute with the value 'http://bluestemsoftware.org/specification/eoa/1.0' (anything else is quietly ignored.)

Schema Fragments

Schema fragments are, as their name implies, used to model only a fragment of the overall schema definition - or more specifically a fragment of a specific schema component. Schema fragments are modeled within the EOA specification by the SchemaFragment class. A schema fragment maps a value extracted from a runtime instance of the indicated schema component, which is extracted via a query, e.g. an xpath query, to a schema property.

...
 <xs:element name="myElement1">
    <xs:annotation xmlns:eoa="http://bluestemsoftware.org/specification/eoa/1.0/component/schema/ext">
      <xs:appinfo source="http://bluestemsoftware.org/specification/eoa/1.0">
        <eoa:fragment property="tns:myProperty1">
          <eoa:query>@myAttribute</eoa:query>
        </eoa:fragment>
      </xs:appinfo>
    </xs:annotation>
    <xs:complexType>
      <xs:attribute name="myAttribute" type="tns:mySimpleType1" />
    </xs:complexType>
  </xs:element>
...  

Schema fragments are declared using the same xs:annotation feature used to declare schema properties as discussed within the schema properties section. Schema fragment definitions are automatically incorporated into all abstract message definitions which reference the schema components upon which the schema fragments are defined, as discussed below. Note that because the referenced property name is used as a proxy for the schema fragment name, you cannot define more than one fragment for the same property within the context of a single schema component declaration, e.g. an element declaration.

Message

A message component abstractly models a runtime message instance. Despite being phased out of the WSDL specification within version 2.0, message components are explicitly modeled within the EOA specification, i.e. via the InterfaceMessage class. This was necessary for two reasons. First of all, WSDL 2.0 is still a relatively 'new' technology. WSDL 1.1 implementations are much more common. In order to be backwards compatible with these implementations, i.e. to enable the invocation of partners which use 'multi-part' messages, an abstract message component is required. Secondly, it provides a static counterpart for a runtime message component, which provides a great deal more functionality than a runtime schema component instance would, e.g. an element instance.

An abstract message component defines message 'parts.' A message part references a schema component which is defined within a schema 'visible' to the message definition (we won't get into the version specific WSDL visibility rules here.) When a WSDL 2.0 definition is read by a wsdl 20 factory, which implements the ComponentReader interface, all global element declarations (GED's) within all deployed schemas (and all transitively referenced schemas) are automatically converted into a 'WSDL 2.0 document style' abstract message instance. A 'WSDL 2.0 document style' message defines a single message part which must be typed as an element. The message part is, by convention, named 'payload' and the qualified name of the payload element is used as proxy for the message component's qualified name. Using the example above, an abstract message instance, of the same name, would be automatically created for the following GED's:

• {http://mycompany.com/business/docs}AvailabilityRequest
• {http://mycompany.com/business/docs}AvailabilityResponse
• {http://mycompany.com/business/docs}ScheduleOrderRequest
• {http://mycompany.com/business/docs}ScheduleOrderResponse
• {http://mycompany.com/business/docs}getOrderStatus
• {http://mycompany.com/business/docs}OrderStatusResponse

Note that if you wish to override this behavior, i.e. to exclude elements that will never be used as a message, you can annotate the element declarations with the following annotation.

...
 <xs:element name="someElement">
   <xs:annotation>
      <xs:appinfo source="http://bluestemsoftware.org/specification/eoa/1.0">
        <eoa:message isMessagePayload="false" xmlns:eoa="http://bluestemsoftware.org/specification/eoa/1.0/component/schema/ext" />
      </xs:appinfo>
    </xs:annotation>
 </xs:element>
...  

Although you will probably never need to do this within your code, i.e. because you'll more than likely be working with runtime message instances which maintain a reference to the abstract message, here's how you would retrieve an abstract message component programmatically:

...

  QName messageName = new QName("http://mycompany.com/business/docs","AvailabilityRequest");
  InterfaceMessage abstractMessage = SystemContext.getContext().getSystem().getMessage(messageName);

...

Message Fragments

A message fragment abstractly defines a value, e.g. a Node , String or Number extracted from a runtime message instance. When an abstract message is created, each schema fragments defined on the schema component referenced by the abstract message's parts is translated into a message fragment. A message fragment is modeled within the EOA specification by the MessageFragment class. You will probably never use this API within your code, but you will, however, indirectly benefit from it when you manipulate a runtime message, as demonstrated within the runtime message section.

One restriction worth pointing out here, is that because a schema fragment's property name attribute is used as a proxy for the message fragment name, and because a message fragment name must be unique within the context of an abstract message, if your abstract message defines more than one part (which is discouraged,) those parts cannot define fragments which are used to extract the same schema property instance.

Interface

An interface is defined via the wsdl:interface element and is modeled within the EOA specification by the Interface class. Using our company metaphor, an interface is comparable to a job description. Just as a job description abstractly describes the job performed by an employee, an interface abstractly describes the service that implements it. An interface's operations are comparable to the tasks defined by the job description. While a job description defines the what part of the description, it doesn't define the how part, i.e. that's typically up to the discretion of each individual employee. Similarly, the way in which a service implements an interface, is different for each service that implements it. The following example, which was borrowed from the spring application demo, shows an example interface declaration which references the type declarations defined above.

<deployment xmlns="http://bluestemsoftware.org/specification/eoa/1.0/deployment">
  <components>
    <wsdl:description xmlns:wsdl="http://www.w3.org/ns/wsdl" targetNamespace="http://software.vendor.com/1.0" xmlns:tns="http://software.vendor.com/1.0">
      <wsdl:types>
        <xs:import namespace="http://mycompany.com/business/docs" xmlns:xs="http://www.w3.org/2001/XMLSchema" />
      </wsdl:types>
      <wsdl:interface name="AvailabilityProcessor" xmlns:ns01="http://mycompany.com/business/docs">
        <wsdl:fault name="OutOfStockFault" element="ns01:OutOfStockFault" />
        <wsdl:operation name="checkAvailability" pattern="http://www.w3.org/ns/wsdl/in-out">
          <wsdl:input element="ns01:AvailabilityRequest" xmlns:wsam="http://www.w3.org/2007/05/addressing/metadata" wsam:Action="urn:checkAvailability" />
          <wsdl:output element="ns01:AvailabilityResponse" xmlns:wsam="http://www.w3.org/2007/05/addressing/metadata" wsam:Action="urn:checkAvailabilityResponse" />
          <wsdl:outfault ref="tns:OutOfStockFault" xmlns:wsam="http://www.w3.org/2007/05/addressing/metadata" wsam:Action="urn:checkAvailabilityOutOfStockFault" />
        </wsdl:operation>
      </wsdl:interface>
      <wsdl:interface name="OrderProcessor" xmlns:ns01="http://mycompany.com/business/docs">
        <wsdl:operation name="scheduleOrder" pattern="http://www.w3.org/ns/wsdl/in-out">
          <wsdl:input element="ns01:ScheduleOrderRequest" xmlns:wsam="http://www.w3.org/2007/05/addressing/metadata" wsam:Action="urn:scheduleOrder" />
          <wsdl:output element="ns01:ScheduleOrderResponse" xmlns:wsam="http://www.w3.org/2007/05/addressing/metadata" wsam:Action="urn:scheduleOrderResponse" />
        </wsdl:operation>
        <wsdl:operation name="getOrderStatus" pattern="http://www.w3.org/ns/wsdl/in-out" style="http://www.w3.org/ns/wsdl/style/iri" xmlns:wsdlx="http://www.w3.org/ns/wsdl-extensions">
          <wsdl:input element="ns01:getOrderStatus" xmlns:wsam="http://www.w3.org/2007/05/addressing/metadata" wsam:Action="urn:getOrderStatus" />
          <wsdl:output element="ns01:OrderStatusResponse" xmlns:wsam="http://www.w3.org/2007/05/addressing/metadata" wsam:Action="urn:getOrderStatusResponse" />
        </wsdl:operation>
      </wsdl:interface>
    </wsdl:description>
  </components>
</deployment>

Interface Fault

Within the EOA specification, an interface fault component models the <wsdl:fault> element (as defined within the context of a <wsdl:interface> element.) It defines the fault's qualified name. The interface fault component is modeled within the EOA specification by the InterfaceFault class. An interface fault component is referenced by an interface action component.

Interface Operation

Within the EOA specification, an interface operation component models the <wsdl:operation> element (as defined within the context of a <wsdl:interface> element.) It defines the operation's qualified name and contains one or more interface actions depending upon the message exchange pattern employed by the interface operation. The interface operation component is modeled within the EOA specification by the InterfaceOperation class. Note that the EOA specification supports the 'in-only', 'robust-in-only' and 'in-out' message exchange patterns. More complicated exchanges can be implemented within your applications, by combining one or more of these basic exchange types.

Interface Action

Within the EOA specification, an interface action component abstracts the <wsdl:input> <wsdl:output> and the <wsdl:outfault> elements, all of which are defined within the context of the <wsdl:interface> element. Note that due to the message exchange patterns supported by the EOA specification, the <wsdl:infault> element is not supported. Each interface action component is identified by its action attribute, the value of which is defined by the ws-addressing specification. If you are not familiar with the ws-addressing specification, we recommend reading the ws-addressing core specification and the ws-addressing metadata specification. If a value is not specified for the wsam:Action attribute, a default value will be generated for you as defined by the ws-addressing metadata specification. In the example above, a value has been explicitly defined for all of the actions, each of which 'overrides' the default value. The action value MUST be unique within the context of the parent interface component. The interface action component is modeled within the EOA specification by the InterfaceAction class.

While this completes our discussion of the WSDL abstract component model, we still have one more component to discuss. The EOA specification 'extends' the WSDL component model by defining an additional top-level, abstract component, which, in our opinion, is 'missing' from the WSDL component model. Just as jobs within a company are typically organized by function, by process, by geography, etc ... so too are interfaces, i.e. within the context of a system. The WSDL specification, however, provides no means by which these relationships can be modeled. This is an important point. If we can abstractly model and describe these relationships using a standardized and portable approach, as facilitated by WSDL, we can then manipulate them abstractly within our code. See the engine assignment section for a demonstration of this concept. The wsdl:application component, which is defined by the EOA specification as an extension to the WSDL specification, solves this problem.

Application

An application component is defined via the wsdl:application element, which is a WSDL extension element, and is modeled within the EOA specification by the Application class. Using our company metaphor, an application is comparable to a department policy manual. Just as a department's policy manual abstractly describes the responsibilities of a department, an application abstractly defines the responsibilities of the engine which implements it. An application component models the relationships between interface components. In software terms, it serves as a model for your e-commerce applications, i.e. as viewed from a partner's perspective. The following example, which was borrowed from the spring application demo, shows an example application component declaration which references the interface declarations defined above.

<deployment xmlns="http://bluestemsoftware.org/specification/eoa/1.0/deployment">
  <components>
    <wsdl:description xmlns:wsdl="http://www.w3.org/ns/wsdl" targetNamespace="http://software.vendor.com/1.0" xmlns:tns="http://software.vendor.com/1.0">
      <ext:application xmlns:ext="http://bluestemsoftware.org/specification/eoa/1.0/component/wsdl/ext" name="WarehouseManager">
        <ext:role name="http://mycompany.com/wm/availability/processor" interface="tns:AvailabilityProcessor" />
        <ext:role name="http://mycompany.com/wm/order/processor" interface="tns:OrderProcessor" />
      </ext:application>
    </wsdl:description>
  </components>
</deployment>

Roles

An application role is a nested component. A role component references an interface which describes the role. An application can implement the same interface more than once as long as the name of the role is unique. Again, using the company metaphor, a department policy manual may define more than one, e.g. supervisor position. While the tasks are roughly the same, the context within which each supervisor performs that particular role will be different. A role component is modeled within the EOA specification by the Role class.

Policy

A policy component models a top-level ws-policy declaration. The policy component can be referenced via various different 'attachment' mechanisms from within the same deployment or from within a different deployment. The policy component is modeled within the EOA specification by the Policy class. Note that the version of ws-policy used is an extension to the core specification. The examples below use version 1.5 of the ws-policy specification. The following example declares four 'top-level' policy components, i.e. which are child elements of the wsdl:description element.

<deployment xmlns="http://bluestemsoftware.org/specification/eoa/1.0/deployment">
  <components>
    <wsdl:description xmlns:wsdl="http://www.w3.org/ns/wsdl" targetNamespace="http://foo">
      <wsp:Policy wsu:Id="A" xmlns:wsp="http://www.w3.org/ns/ws-policy" xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd">
        <wsp:ExactlyOne>
          <dns:foo xmlns:dns="http://foo" />
        </wsp:ExactlyOne>
      </wsp:Policy>
    </wsdl:description>
    <wsdl:description xmlns:wsdl="http://www.w3.org/ns/wsdl" targetNamespace="http://bar">
      <wsp:Policy wsu:Id="A" xmlns:wsp="http://www.w3.org/ns/ws-policy" xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd">
        <wsp:ExactlyOne>
          <dns:foo xmlns:dns="http://bar" />
        </wsp:ExactlyOne>
      </wsp:Policy>
    </wsdl:description>
  </components>
</deployment>

Because a policy component is a top-level component, it is identified by its qualified name. Policy components acquire the target namespace of the enclosing WSDL document. In the example above, the policy component names are {http://foo}A, and {http://bar}A. Note that the 'wsu:Id' attribute is optional. If undefined, the policy component's local name is the empty string.

Policy Attachment

A policy expression can be 'attached' to a component using three different attachment mechanisms, the first of which is the simplest, i.e. 'in-lining' the expression within the element to which it is 'attached,' e.g.

<deployment xmlns="http://bluestemsoftware.org/specification/eoa/1.0/deployment">
  <components>
    <wsdl:description xmlns:wsdl="http://www.w3.org/ns/wsdl" targetNamespace="http://some/uri" xmlns:tns="http://some/uri" xmlns:wsp="http://www.w3.org/ns/ws-policy">
      <wsdl:interface name="someInterface" xmlns:ns01="http://mycompany.com">
        <wsdl:fault name="SomeFault" element="ns01:myFaultElement" />
        <wsdl:operation name="somOperation" pattern="http://www.w3.org/ns/wsdl/in-only">
          <wsdl:input element="ns01:myInputElement">
            <wsp:Policy>
              <wsp:ExactlyOne>
                <dns:foo xmlns:dns="http://test" />
              </wsp:ExactlyOne>
            </wsp:Policy>
          </wsdl:input>
        </wsdl:operation>
      </wsdl:interface>
    </wsdl:description>
  </components>
</deployment>

The second attachment mechanism references a policy component which can be defined within the same deployment, or within a different deployment, via the <wsp:PolicyReference> element. The policy component is referenced by its fragment identifier, e.g.

<deployment xmlns="http://bluestemsoftware.org/specification/eoa/1.0/deployment">
  <components>
    <wsdl:description xmlns:wsdl="http://www.w3.org/ns/wsdl" targetNamespace="http://baz" xmlns:tns="http://baz" xmlns:wsp="http://www.w3.org/ns/ws-policy">
      <wsdl:types>
        <xs:schema targetNamespace="http://mycompany.com" elementFormDefault="qualified" xmlns:xs="http://www.w3.org/2001/XMLSchema">
          <xs:element name="myInputElement" />
          <xs:element name="myOutputElement" />
        </xs:schema>
      </wsdl:types>
      <wsdl:interface name="myinterface" xmlns:ns01="http://mycompany.com">
        <wsdl:operation name="myoperation" pattern="http://www.w3.org/ns/wsdl/in-out">
          <wsdl:input element="ns01:myInputElement">
            <wsp:PolicyReference URI="#http://foo%23eoa.policy(A)" />
          </wsdl:input>
          <wsdl:output element="ns01:myOutputElement">
            <wsp:PolicyReference URI="#http://bar%23eoa.policy(A)" />
          </wsdl:output>
        </wsdl:operation>
        <wsp:PolicyReference URI="#A" />
      </wsdl:interface>
      <wsp:Policy wsu:Id="A" xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd">
        <wsp:ExactlyOne>
          <dns:foo xmlns:dns="http://test" />
          <wsp:PolicyReference URI="#B" />
        </wsp:ExactlyOne>
      </wsp:Policy>
    </wsdl:description>
  </components>
</deployment>

When referencing a policy component which is defined within a targetNamespace other than the targetNamespace of the enclosing document, the fragment identifier must be fully qualified. The first two references in the example above, which reference the policy components which were defined within the policy declaration example, are fully qualified. Note that the second '#' symbol in the fragment id must be escaped or its not a legal URI fragment.

If the referenced policy component is defined within the same targetNamespace as the enclosing WSDL document, the targetNamespace portion of the fragment identifier is implied and only the 'pointer part' is required, as is the case with the last policy reference in the example above. The last attachment method uses the 'wsp:PolicyURIs' attribute, which defines a list of referenced policy components, e.g.

<deployment xmlns="http://bluestemsoftware.org/specification/eoa/1.0/deployment">
  <components>
    <wsdl:description xmlns:wsdl="http://www.w3.org/ns/wsdl" targetNamespace="http://baz" xmlns:tns="http://baz" xmlns:wsp="http://www.w3.org/ns/ws-policy">
      <wsdl:types>
        <xs:schema targetNamespace="http://mycompany.com" elementFormDefault="qualified" xmlns:xs="http://www.w3.org/2001/XMLSchema">
          <xs:element name="myInputElement" />
          <xs:element name="myOutputElement" />
          <xs:element name="myFaultElement" />
        </xs:schema>
      </wsdl:types>
      <wsdl:interface name="someInterface" xmlns:ns01="http://mycompany.com">
        <wsdl:fault name="someFault" element="ns01:myFaultElement" />
        <wsdl:operation name="someOperation" pattern="http://www.w3.org/ns/wsdl/in-out">
          <wsdl:input element="ns01:myInputElement"/>
          <wsdl:output element="ns01:myOutputElement"/>
          <wsdl:outfault ref="someFault" wsp:PolicyURIs="#http://foo%23eoa.policy(A) #http://bar%23eoa.policy(A)" />
        </wsdl:operation>
      </wsdl:interface>
    </wsdl:description>
  </components>
</deployment>    

As required by the ws-policy specification, the list of URI's are separated by a space. The example above references the two policy components which were defined within the policy declaration example. Note that in all of the attachment examples above, if the policy document is defined remotely, an absolute URL would be used to define the location.

The point at which a policy expression is attached defines its policy subject. Policy subjects and runtime policy manipulation are discussed within the section on policy expressions.

Concrete Components

A concrete component provides an implementation of the behavior defined by its abstract counterpart. As an example, using our company metaphor, a job description is an abstract concept, whereas the employee that performs that job is a concrete implementation of that description.

Binding

A binding component is defined via the wsdl:binding element and is modeled within the EOA specification by the Binding class. Of all the components within the WSDL component model, the binding component is the most difficult to understand. We'll attempt to simplify the concept (really simplify) by using our company metaphor to describe its behavior. For a list of the available binding types, please see the extension reference page.

The binding component can, in terms of its responsibility, be compared to a company's mail room. Just as a mail room within a company encapsulates the specifics of interacting with the available mail carriers, e.g. USPS, UPS, Federal Express, etc ..., a binding encapsulates the behavior required to interact with the various transport and messaging protocols, e.g. HTTP and SOAP. Within a company, an employee simply drops the envelope in the mail slot and the mail room manages the complexities of interacting with the various carriers. All the employee has to be concerned with is the content of the document contained within the envelope and making sure that the address of the person to whom the envelope is to be sent is correct (with the option of defining additional 'quality of service' requirements related to the delivery, which will be discussed in a later section.) A binding component performs roughly the same responsibilities. It allows a service to focus on just the message payload, i.e. the 'business logic' portion of the exchange, without having to worry about the complexities of how the message is actually formatted and transmitted over 'the wire.' Note that within WSDL 2.0, binding's are re-usable, so you have the option of defining one 'mail room' for the whole company, one per department, etc ....

Binding Fault

Within the EOA specification, a binding fault component models the <wsdl:fault> element (as defined within the context of a <wsdl:binding> element.) It defines the fault's qualified name. The binding fault component is modeled within the EOA specification by the BindingFault class. A binding fault component is referenced by a binding action component.

Binding Operation

Within the EOA specification, a binding operation component models the <wsdl:operation> element (as defined within the context of a <wsdl:binding> element.) Note that if a binding defines one or more operations, it is not 're-usable.' A 're-usable' binding is one that can be used to bind more than one interface, i.e. by implementing a default set of binding type specific rules. The binding operation component is modeled within the EOA specification by the BindingOperation class.

Binding Action

Within the EOA specification, a binding action component abstracts the <wsdl:input> <wsdl:output> and the <wsdl:outfault> elements, all of which are defined within the context of the <wsdl:binding> element. Note that because the EOA specification supports the 'in-only', 'robust-in-only' and 'in-out' message exchange patterns, the <wsdl:infault> element is not supported. Each binding action binds a set of binding specific rules to an abstract action component. The binding action component is modeled within the EOA specification by the BindingAction class.

Service

A service component is defined via the wsdl:service element and is modeled within the EOA specification by the Service class. Using our company metaphor, a service is comparable to an employee. Just as an employee performs his or her job by implementing their job description, a service performs its responsibility by implementing the interface it exposes to its partners. The following example, which was borrowed from the spring application demo, shows an example service component declaration which references the interface declarations defined above.

<deployment xmlns="http://bluestemsoftware.org/specification/eoa/1.0/deployment">
  <components>
    <wsdl:description xmlns:wsdl="http://www.w3.org/ns/wsdl" targetNamespace="http://my.company.com/wm/atlanta/1.0" xmlns:tns="http://my.company.com/wm/atlanta/1.0" xmlns:ns01="http://software.vendor.com/1.0">
      <wsdl:binding name="SOAP12Binding" type="http://www.w3.org/ns/wsdl/soap" xmlns:wsoap="http://www.w3.org/ns/wsdl/soap" wsoap:version="1.2" wsoap:protocol="http://www.w3.org/2003/05/soap/bindings/HTTP/" />
      <wsdl:service name="AvailabilityService" interface="ns01:AvailabilityProcessor">
        <wsdl:endpoint name="SOAP12Endpoint" binding="tns:SOAP12Binding" xmlns:whtp="http://www.w3.org/ns/wsdl/http" whtp:authenticationScheme="basic" whtp:authenticationRealm="warehouse" address="http://localhost:8082/eoa/ws/xmlns(ns=http://my.company.com/wm/atlanta/1.0)ns:AvailabilityService/SOAP12Endpoint/">
        </wsdl:endpoint>
      </wsdl:service>
      <wsdl:service name="OrderService" interface="ns01:OrderProcessor">
        <wsdl:endpoint name="SOAP12Endpoint" binding="tns:SOAP12Binding" xmlns:whtp="http://www.w3.org/ns/wsdl/http" whtp:authenticationScheme="basic" whtp:authenticationRealm="warehouse" address="http://localhost:8082/eoa/ws/xmlns(ns=http://my.company.com/wm/atlanta/1.0)ns:OrderService/SOAP12Endpoint/">
        </wsdl:endpoint>
      </wsdl:service>
    </wsdl:description>
  </components>
</deployment>

Endpoint

Within the EOA specification, an endpoint component models the <wsdl:endpoint> element. It defines a choice of binding semantics offered by the parent service which can be accessed via the indicated location URI. An endpoint is modeled within the EOA specification by the Endpoint class. An endpoint component defines one or more endpoint operation components.

Endpoint Operation

Within the EOA specification, an endpoint operation component represents a concrete manifestation of the interface operation component. Note that the endpoint operation component has no corresponding element within the XML representation of a <wsdl:service.> Its definition is instead implied and automatically created for you. An endpoint operation component is created for each abstract operation defined on the interface component implemented by the parent service component. The endpoint operation component is modeled within the EOA specification by the EndpointOperation class.

Endpoint Action

Within the EOA specification, an endpoint action component represents a concrete manifestation of the interface action component. It is 'nested' within its parent endpoint operation component. Note that the endpoint action component has no corresponding element within the XML representation of a <wsdl:service.> Its definition is instead implied and automatically created for you. An endpoint action component is created for each abstract action defined on the abstract operation referenced by the parent endpoint operation component. The endpoint action component is modeled within the EOA specification by the EndpointAction class.

Engine

An engine component is defined via the wsdl:engine element, which is a WSDL extension element, and is modeled within the EOA specification by the Engine class. An engine implements an application, just as a service implements an interface. Using our company metaphor, an engine is comparable to a department within a company. A department is a concrete manifestation of its abstract form. It implements department policy. The following example, which was borrowed from the spring application demo, shows an example engine component declaration which references the application declaration defined above.

<deployment xmlns="http://bluestemsoftware.org/specification/eoa/1.0/deployment">
  <components>
    <wsdl:description xmlns:wsdl="http://www.w3.org/ns/wsdl" targetNamespace="http://my.company.com/wm/atlanta/1.0" xmlns:tns="http://my.company.com/wm/atlanta/1.0" xmlns:ns01="http://software.vendor.com/1.0">
      <ext:engine xmlns:ext="http://bluestemsoftware.org/specification/eoa/1.0/component/wsdl/ext" name="WarehouseManagerEngine" application="ns01:WarehouseManager">
        <ext:actor role="http://mycompany.com/wm/availability/processor" service="tns:AvailabilityService" />
        <ext:actor role="http://mycompany.com/wm/order/processor" service="tns:OrderService" />
      </ext:engine>
    </wsdl:description>
  </components>
</deployment>

Actors

An engine is essentially a collection of related services, each of which acts out a role defined by the referenced application. Each actor component references a service, i.e. the service that performs the role indicated by its 'role' attribute. An actor must be defined for every role defined on the application implemented by the engine, and the interface referenced by the role must be the interface implemented by the referenced service. An actor component is modeled within the EOA specification by the Actor class.

Defining Connectors

A connector is essentially a factory for creating type specific connections to a resource manager, e.g. a database server, JMS server, ERP system, etc ... Each resource manager implementation typically requires its own specific connector type. Note that a list of the available connector implementations, listed by category, along with usage examples, can be found within the extensions reference. A connector is modeled within the EOA specification by the Connector class.

Connectors are defined within a container definition. Each connector definition defines a simple name and information regarding the factory deployment which is used by the container to instantiate the connector. The following example demonstrates how to define a connector used to create connections to a derby DBMS within the context of the default container implementation.

<container xmlns="http://bluestemsoftware.org/specification/eoa/ext/container/standalone/1.0/">
  <transactionSupport enable="true"/>
  <connectors>
    <connector type="org.bluestemsoftware.specification.eoa.ext.connector.db.DataSourceConnector" impl="org.bluestemsoftware.open.eoa.ext.connector.db.derby.client.DataSourceConnectorImpl" name="myDataSource">
      <properties>
        <property name="serverName">somehost</property>
        <property name="portNumber">1110</property>
        <property name="databaseName">someDB</property>
        <property name="userName">sa</property>
      </properties>
      <connectionSupport>
        <transactionSupport type="LOCAL" />
        <poolingSupport type="SINGLE">
          <minPoolSize>1</minPoolSize>
          <maxPoolSize>10</maxPoolSize>
        </poolingSupport>
      </connectionSupport>
    </connector>
  </connectors>
</container>

And the following example demonstrates how you would retrieve and use the connector within your application code.

...

  // retrieve a reference to the naming context which can be used
  // to retrieve your connector. note that as required by the EOA
  // specification, the container binds each connector within the
  // 'java:comp/connectors' namespace

  Context context = new InitialContext();
  Connector connector = (Connector) context.lookup("java:comp/connectors/myDataSource");
  
  // alternatively, the 'middleware' api can be used to retrieve
  // a reference to the connector, e.g.
  
  Container container = SystemContext.getContext().getSystem().getContainer();
  connector = container.getConnector("myDataSource");
  
  // cast the connector to the 'well-known' type - DataSource
  // and use it to create a connection to the dbms
  
  javax.sql.DataSource dataSource = (javax.sql.DataSource)connector;
  java.sql.Connection connection = dataSource.getConnection();

...

Again, note that the availability of the naming context assumes that a feature which implements the naming and directory services functionality has been enabled on the server, which would be defined as a feature dependency by the deployment within which your application is defined.

Enabling Features

A feature encapsulates an abstract 'piece' of behavior which is used to extend the behavior of an EOA system as discussed within the section on features. Before a feature can be used, it must be explicitly enabled within the server definition. This 'extra' step was designed into the EOA specification to mitigate the possibility of introducing rogue features into the system, i.e. as opposed to lazily instantiating features on demand using a default configuration.

Features are enabled within the server.xml file. The means by which a feature is enabled is server implementation specific, but the approach should be fairly similar across implementations. Each entry which enables a feature, as depicted below, should at a minimum define the feature type. The type is used by the server to retrieve a feature factory instance which is used to instantiate the feature. Note that a listing of available features listed by type, including configuration schemas and example usages can be found here.

<server xmlns="http://bluestemsoftware.org/specification/eoa/ext/server/standalone/1.0/">
  <features>
    <feature type="org.bluestemsoftware.specification.eoa.ext.feature.ws.addressing.soap.WSAFeature" />
    <feature type="org.bluestemsoftware.specification.eoa.ext.feature.http.client.HTTPClientFeature">
      <provider impl="org.bluestemsoftware.open.eoa.ext.feature.http.client.commons.HTTPClientFeatureImpl">
        <cfg:httpclient xmlns:cfg="http://bluestemsoftware.org/open/eoa/ext/feature/http/client/commons/config/1.0">
          <cfg:client>
            <cfg:properties>
              <cfg:property name="http.authentication.preemptive" value="true" />
            </cfg:properties>
          </cfg:client>
        </cfg:httpclient>
      </provider>
    </feature>
  </features>
</server>

If the entry fails to define a specific implementation, e.g. the WSAFeature entry above, and more than one feature factory of that type is defined within the context of the system, the server will retrieve an arbitrary factory implementation and use it to create the feature (using the feature's default configuration.)

An entry can optionally define a specific implementation of the indicated feature type, e.g. the HTTPClientFeature entry above, along within an optional, provider specific configuration element. If an implementation is defined, the server will use both the type and implementation as arguments when retrieving the feature factory and will pass the configuration element, if defined, to the feature when it is initialized.

Note that when the server enables a feature, features upon which the feature may depend, as discussed within the section on feature dependencies, are enabled first. Features are disabled in the reverse order in which they were enabled. The following example demonstrates how you would retrieve and use a feature from within your application code.

...

  // retrieve a reference to the server and use it to retrieve the
  // feature by passing the type as an argument. note that the api
  // uses generic typing which precludes having to cast the feature
  // to a specific type
  
  Server server = SystemContext.getContext().getSystem().getServer();
  HTTPClientFeature feature = server.getFeature(HTTPClientFeature.class);
  
  // then we use the feature, e.g. the HTTPClientFeature, to create
  // an http client instance
  
  HTTPClient httpClient = feature.createHTTPClient();

...

Schema Documents

A schema document provides a static schema component's runtime behavior. It is modeled within the EOA specification by the SchemaDocument interface which extends org.w3c.dom.Document. A list of the available implementations can be found on the extensions reference page. A schema document can be used to validate an element instance which it defines, e.g.

...

public void foo(Element myElement) throws SchemaException {
    
  // retrieve the schema by qualified name
  QName schemaName = new QName("http://mycompany.com/business/docs","MyMessages");
  Schema schema = SystemContext.getContext().getSystem().getSchema(schemaName);
  
  // retrieve its runtime provider
  SchemaDocument runtimeSchema = schema.getRuntimeProvider();
  
  // now assuming that the declaration which defines the
  // myElement instance is defined within the schema,
  // we validate it
  
  try {
      runtimeSchema.validate(myElement);
  } catch (SchemaValidationException sve) {
      // handle the validation error
  }
    
}

...

Runtime Messages

A runtime message component provides an abstract message component's runtime behavior. A runtime message is modeled within the EOA specification by the Message class. Depending upon the type specific application API employed by your application, e.g. the spring application API, this is one of the objects within the 'middleware' API that will more than likely be used within your code. Alternatively, your API might completely 'hide' the middleware API by delivering just an Element instance, i.e. the message payload, to your applications. The runtime message object provides several key pieces of functionality, e.g. message fragments (which will be demonstrated within the runtime engines section) and message modules.

Note that as discussed above, the namespace used to define the provider declaration, identifies the message type. This example uses our 'default message' implementation. For a list of available runtime message implementations, please see the extension reference page. To declare runtime instances of the abstract messages declared within the types declaration example above, recalling that, as discussed within the abstract message section, a WSDL 2.0 document style message is created for each GED, requires the following provider declarations.

<deployment xmlns="http://bluestemsoftware.org/specification/eoa/1.0/deployment">
  <providers>
    <eoa:message xmlns:eoa="http://bluestemsoftware.org/specification/eoa/ext/message/default/1.0" xmlns:tns="http://mycompany.com/business/docs" name="tns:AvailabilityRequest">
      <payload xmlns="">
        <AvailabilityRequest xmlns="http://mycompany.com/business/docs">
          <ZipCode />
          <Items />
        </AvailabilityRequest>
      </payload>
    </eoa:message>
    <eoa:message xmlns:eoa="http://bluestemsoftware.org/specification/eoa/ext/message/default/1.0" xmlns:tns="http://mycompany.com/business/docs" name="tns:AvailabilityResponse">
      <payload xmlns="">
        <AvailabilityResponse xmlns="http://mycompany.com/business/docs">
          <ShippingCost />
        </AvailabilityResponse>
      </payload>
    </eoa:message>
    <eoa:message xmlns:eoa="http://bluestemsoftware.org/specification/eoa/ext/message/default/1.0" xmlns:tns="http://mycompany.com/business/docs" name="tns:ScheduleOrderRequest">
      <payload xmlns="">
        <ScheduleOrderRequest xmlns="http://mycompany.com/business/docs" />
      </payload>
    </eoa:message>
    <eoa:message xmlns:eoa="http://bluestemsoftware.org/specification/eoa/ext/message/default/1.0" xmlns:tns="http://mycompany.com/business/docs" name="tns:ScheduleOrderResponse">
      <payload xmlns="">
        <ScheduleOrderResponse xmlns="http://mycompany.com/business/docs" />
      </payload>
    </eoa:message>
    <eoa:message xmlns:eoa="http://bluestemsoftware.org/specification/eoa/ext/message/default/1.0" xmlns:tns="http://mycompany.com/business/docs" name="tns:OrderStatusResponse">
      <payload xmlns="">
        <OrderStatusResponse xmlns="http://mycompany.com/business/docs" />
      </payload>
    </eoa:message>
  </providers>
</deployment>

The definitions above are all WSDL 2.0 document style message instances, i.e. they all define a single part typed as an element - as required by the static definition. For examples on how to declare multi-part, 'default' message instances, please see the following reference. Note that runtime message components, unlike other runtime component types, do not have to be defined within the same deployment as its static counterpart. When a binding and/or engine creates a runtime message instance, it first checks to see if a provider has been defined within the application's component deployment. If not, the component deployment within which the referenced element decl was declared is checked. If still not found, an 'empty' runtime message instance is created, i.e. one with no content.

Action Context

While the static interface component has no runtime manifestation within the EOA component model, the InterfaceAction components, which are nested within it, do. This manifestation is modeled within the EOA specification by the ActionContext class. The action context object models the context within which a runtime action exists. When a runtime message is received by, or sent from, a runtime engine instance, it is encapsulated within an action context object along with another artifact of action processing - message modules.

Message Modules

A message module component is modeled within the EOA specification by the MessageModule class. Message modules are an artifact of feature module processing. Using our company metaphor, message modules are comparable to the labels affixed to the outside of an envelope which define 'quality of service' (QOS) requirements that are specific to that package. The labels are carrier specific. For example, when sending a letter via USPS, UPS or Federal Express, you can purchase additional QOS related services, e.g. overnight delivery, return receipt, etc ... the parameters for which are defined on a service specific label. The mail room personnel that handle the envelopes, must have an 'understanding' of the carrier specific rules which define these QOS related services in order to generate and affix the correct labels.

Similarly, binding modules, which are binding type specific, must understand the policy which serves to enable/constrain them, i.e. such that they can apply QOS specific rules when processing the protocol specific message headers. The artifact which results from this header processing is a message module. Note that message module's are protocol agnostic, i.e. all binding specific attributes, e.g. SOAP 'actor' and 'mustUnderstand' attributes, have been removed. Because applications may use message modules, e.g. the application data module, it is important that binding specific semantics are not 'leaked' into the 'application layer.'

Runtime Bindings

A runtime binding, which is modeled within the EOA specification by the BindingRT class, provides a static binding component's runtime behavior. The majority of a runtime binding component's behavior is strictly defined by the WSDL specification. The underlying provider should, however, provide a means by which its specific implementation of the behavior can be configured. As an example, the following provider entry is used to configure the runtime binding instance which provides the runtime behavior for its static counter part which was defined within the service declaration example listed above.

<deployment xmlns="http://bluestemsoftware.org/specification/eoa/1.0/deployment">
  <providers>
    <binding xmlns="http://bluestemsoftware.org/specification/eoa/ext/binding/soap/default/1.0" xmlns:tns="http://my.company.com/wm/atlanta/1.0" name="tns:SOAP12Binding">
      <configuration>
        <embedStackTraceInFaults>true</embedStackTraceInFaults>
        <requestorTimeout>6000000</requestorTimeout>
        <minHeaderProcessors>5</minHeaderProcessors>
        <maxPayloadProcessors>5</maxPayloadProcessors>
      </configuration>
    </binding>
  </providers>
</deployment>

The settings above, control implementation specific behavior. For more information regarding each specific setting, please refer to the SOAPBinding configuration schema. Note that this is an optional step that is only required if you wish to modify a provider's default configuration. A runtime binding component is automatically created for each static binding component defined within your component deployments, as well as those transitively referenced by your component deployments. The implication here, is that you should be careful to exclude any 'un-used' binding declarations, i.e. to avoid the instantiation of resources, e.g. JMS queues, that will never be used. Note that unlike runtime application and runtime engine components, runtime binding components are required for partner invocation.

Runtime Application

A runtime application, which is modeled within the EOA specification by the ApplicationRT interface, provides a static application component's runtime behavior. The following example, which was borrowed from the spring application demo, and which was adapted to use the default application type (for a list of the available application types, please see the extension reference page) declares a runtime application component for the WarehouseManager application component declared above. Note that the WarehouseManager application declares only itself as a partner, which serves two purposes. Firstly, it allows for recursive invocation. Secondly, it creates a structure which mirrors the static, abstract component model. This is important, because it provides us with a place where we can attach private policy, which in this case, would have policy subject endpoint. Note that for this particular application type, if the 'partners' element is omitted, the reference to self will be automatically created for you. If an application has partners other than itself, however, they must be explicitly defined. We'll discuss application partners within the next section.

<deployment xmlns="http://bluestemsoftware.org/specification/eoa/1.0/deployment">
  <providers>
    <application xmlns="http://bluestemsoftware.org/open/eoa/ext/application/default/1.0" xmlns:tns="http://software.vendor.com/1.0" name="tns:WarehouseManager">
      <partners>
        <applicationReference applicationName="tns:WarehouseManager">
          <roleReference roleName="http://mycompany.com/wm/availability/processor">
            <!-- attach private policy with subject ENDPOINT here -->
          </roleReference>
          <roleReference roleName="http://mycompany.com/wm/order/processor">
            <!-- attach private policy with subject ENDPOINT here -->
          </roleReference>
        </applicationReference>
      </partners>
    </application>
  </providers>
</deployment>

So the question you may be asking is - how does an application component behave at runtime? The answer is - it depends. It depends upon the application type, which is defined as an extension to the core EOA specification. As depicted below, the static component, i.e. the wsdl:application, is a collection of roles each of which references a wsdl:interface. Note that the static representation is the same regardless of how the application is implemented, i.e. regardless of the application type. To help clarify the question posed above, however, we'll use the spring application type as an example. Because the spring application type uses the java programming language to 'model' the application's runtime form, the runtime application represents a set of java interfaces, i.e. one for each role defined on the static application.

  

The diagram above reinforces an important concept, i.e. that the application component is abstract. Just as a java interface can't be instantiated, an application component can't be 'instantiated' either. To be instantiated, the runtime application requires a runtime engine to implement it, just as a java interface must be implemented by a java class. Once instantiated, however, the abstract then becomes concrete. So, to continue the analogy, within the context of the spring application type, the runtime engine which implements the runtime application represents a collection of classes, a subset of which must implement the java interfaces defined by the runtime application it implements.

Other application types may manifest the static wsdl:application component differently at runtime, e.g. an xml based process language such as BPEL4WS would require that the runtime application be modeled as objectified XML whereas the runtime engine that implements it, would represent a 'compiled' and executable version of the process.

Application Partners

A runtime application can define 'partners.' Partners serve to model an application's relationship with other applications, i.e. other applications that it requires in order to implement its behavior. Note these relationships are locally defined, i.e. they are not a part of the application's public WSDL definition. The following example, which was borrowed from the spring application demo, and which was adapted to use the default application type, defines a runtime OrderManager application. In addition to defining itself as a partner (which allows for recursive invocation,) it defines the WarehouseManager application as a partner, e.g.

<deployment xmlns="http://bluestemsoftware.org/specification/eoa/1.0/deployment">
  <providers>
    <application xmlns="http://bluestemsoftware.org/specification/eoa/ext/application/default/1.0" xmlns:tns="http://com.mycompany/eoa/om/1.0" name="tns:OrderManager">
      <partners>
        <applicationReference applicationName="tns:OrderManager">
          <roleReference roleName="http://mycompany.com/om/order/processor"/>
        </applicationReference>
        <applicationReference xmlns:ns="http://software.vendor.com/1.0" applicationName="ns:WarehouseManager">
          <roleReference roleName="http://mycompany.com/wm/order/processor"/>
        </applicationReference>
      </partners>
    </application>
  </providers>
</deployment>

Note that the deployment which contains the runtime OrderManager application definition must define the component deployment which contains the runtime WarehouseManager application as a dependency as discussed within the section on component dependencies. Which, by the way, introduces an interesting side effect. By defining dependencies upon one another, the chain of dependent runtime applications could be quite long, e.g. A depends on B which depends on C which depends on D, etc... How do you indicate which runtime application definitions get loaded into a specific system instance? If you only intend to execute an instance of application A, i.e. via a runtime engine which implements A, you wouldn't want to load the runtime definitions for B, C, and D.

To resolve this ambiguity, the EOA specification indicates that only runtime applications whose definition is contained within a deployment which was not resolved transitively, i.e. from the perspective of the system, are actually loaded. So, using the example above, to deploy only runtime application A requires that only it be defined as a system dependency, i.e. within the system instance's POM. Only the static portion of the component model for transitively referenced application components is deployed.

Application Component Model

The runtime application component model mirrors the static application component model by defining runtime components which 'reference' their static counterparts. The references are established when the deployment is deployed. If any references are 'broken,' the component will fail to deploy. A runtime application component's partners are defined via its application reference components.

  

Application Reference

An application reference component, which is modeled within the EOA specification by the ApplicationReference interface, is nested within its parent runtime application component. Within the runtime OrderManager declaration above, in addition to declaring itself as a partner, which allows for recursive invocation and provides a place to attach private policy, the OrderManager defines the WarehouseManager application as a partner by defining an application reference component which references the WarehouseManager application.

  

Role Reference

A role reference component references the static role component. It is modeled within the EOA specification by the RoleReference interface. A role reference component is required for each role component defined on the referenced application. Note that, while application type dependent, if a role reference component is not explicitly defined, it should be created for you.

Runtime Engines

A runtime engine component is responsible for instantiating and executing a runtime application. The runtime engine component is modeled within the EOA specification by the EngineRT class. The following example, which was borrowed from the spring application demo, and which was adapted to use the default engine type (for a list of the available engine types, please see the extension reference page) declares a runtime engine component which implements the WarehouseManager application declared above.

<deployment xmlns="http://bluestemsoftware.org/specification/eoa/1.0/deployment">
  <providers>
    <engine xmlns="http://bluestemsoftware.org/specification/eoa/ext/engine/default/1.0" xmlns:tns="http://my.company.com/wm/atlanta/1.0" name="tns:WarehouseManagerEngine">
      <partners>
        <engineReference engineName="tns:WarehouseManagerEngine">
          <serviceReference serviceName="tns:AvailabilityService">
            <endpointReference endpointName="SOAP12Endpoint">
              <operationReference xmlns:ns="http://software.vendor.com/1.0" operationName="ns:checkAvailability">
                <actionReference action="urn:checkAvailability">
                  <!-- attach private policy with subject MESSAGE here -->
                </actionReference>
                <actionReference action="urn:checkAvailabilityResponse">
                  <!-- attach private policy with subject MESSAGE here -->
                </actionReference>
                <actionReference action="urn:checkAvailabilityOutOfStockFault">
                  <!-- attach private policy with subject MESSAGE here -->
                </actionReference>
                <!-- attach private policy with subject OPERATION here -->
              </operationReference>
              <!-- attach private policy with subject ENDPOINT here -->
            </endpointReference>
            <!-- attach private policy with subject SERVICE here -->
          </serviceReference>
          <serviceReference serviceName="tns:OrderService">
            <endpointReference endpointName="SOAP12Endpoint">
              <operationReference xmlns:ns="http://software.vendor.com/1.0" operationName="ns:scheduleOrder">
                <actionReference action="urn:scheduleOrder">
                  <!-- attach private policy with subject MESSAGE here -->
                </actionReference>
                <actionReference action="urn:scheduleOrderResponse">
                  <!-- attach private policy with subject MESSAGE here -->
                </actionReference>
                <!-- attach private policy with subject OPERATION here -->
              </operationReference>
              <operationReference xmlns:ns="http://software.vendor.com/1.0" operationName="ns:getOrderStatus">
                <actionReference action="urn:getOrderStatus">
                  <!-- attach private policy with subject MESSAGE here -->
                </actionReference>
                <actionReference action="urn:getOrderStatusResponse">
                  <!-- attach private policy with subject MESSAGE here -->
                </actionReference>
                <!-- attach private policy with subject OPERATION here -->
              </operationReference>
              <!-- attach private policy with subject ENDPOINT here -->
            </endpointReference>
            <!-- attach private policy with subject SERVICE here -->
          </serviceReference>
        </engineReference>
      </partners>
    </engine>
  </providers>
</deployment>

Note that the WarehouseManagerEngine declares only itself as a partner, which serves two purposes. Firstly, it allows for recursive invocation. Secondly, it creates a structure which mirrors the static, concrete component model. This is important, because it provides us with a place where we can attach our private policy. Note that for this particular engine type, if the 'partners' element is omitted, the reference to self will be automatically created for you. Also, if you omit any part of the nested structure within any partner declaration, it will be auto-generated as well. This behavior should apply to other engine types, unless the nested component has type specific attribute(s) which cannot be defaulted.

Engine Partners

For each partner defined by the runtime application, the runtime engine must define at least one partner engine which implements that application. Within the example below, which was also borrowed from the spring application demo, and which was adapted to use the default engine type, more than one partner engine has been defined which implements the WarehouseManager application.

<deployment xmlns="http://bluestemsoftware.org/specification/eoa/1.0/deployment">
  <providers>
    <engine xmlns="http://bluestemsoftware.org/specification/eoa/ext/engine/default/1.0" xmlns:tns="http://com.mycompany/eoa/om/1.0" name="tns:OrderManagerEngine">
      <partners>
        <engineReference xmlns:ns="http://my.company.com/wm/atlanta/1.0" engineName="ns:WarehouseManagerEngine"/>
        <engineReference xmlns:ns="http://my.company.com/wm/dallas/1.0" engineName="ns:WarehouseManagerEngine"/>
        <engineReference xmlns:ns="http://my.company.com/wm/chicago/1.0" engineName="ns:WarehouseManagerEngine"/>
      </partners>
    </engine>
  </providers>
</deployment>

As, discussed above within the section on runtime application partners, the EOA specification indicates that only runtime engines whose definition is defined as a system dependency, i.e. within the system instance's POM, are deployed. Only the static portion of the component model for transitively referenced engine components is deployed.

Engine Assignment

As demonstrated in the example above, the ability to declare multiple partners of the same abstract type, enables a very powerful feature, i.e. the ability to assign an engine at runtime, within your applications. Please refer to the code snippet defined within the spring application demo for an example. From the perspective of the OrderManager application, the WarehouseManager application instances which are executing within Atlanta, Dallas and Chicago are all identical. Logic within the OrderManager application, i.e. the business logic, determines, at runtime which specific partner to invoke, which in this example uses the customer zip code to locate a warehouse in closest proximity to the customer.

By performing a single assignment operation, the OrderManager application can then invoke the various operations defined on the various roles implemented by the WarehouseManager application without having to manipulate specific endpoints. Endpoint manipulation is the approach employed by most, if not all, other integration platforms. This is important for two reasons. Firstly, the manipulation of endpoints imply an understanding of binding semantics. Application's should be concerned with only the business logic, i.e. not which particular version of SOAP an endpoint employs or whether it employs anonymous or non-anonymous responses, etc ... Leaking binding semantics into the application layer makes for brittle applications. These decisions should instead be made at deployment time.

Secondly, when an application defines multiple roles, as is the case with most applications other than those which define a single 'utility' type interface, manipulating endpoints within your code (or within XML based process languages, etc ...) can get messy. And as developers, we all know that when it comes to application design, simpler is better. Simpler applications are easier to develop, easier to maintain, and have fewer bugs.

Engine Component Model

The runtime engine component model mirrors the static engine component model by defining runtime components which 'reference' their static, concrete counterparts. The references are established when the deployment is deployed. If any references are 'broken,' the component will fail to deploy. A runtime engine component's partners are defined via its engine reference components.

  

Engine Reference

An engine reference component, which is modeled within the EOA specification by the EngineReference class, is nested within its parent runtime engine component. Within the runtime OrderManagerEngine declaration above, in addition to declaring itself as a partner, which allows for recursive invocation and also provides a place to attach private policy, the OrderManagerEngine defines three separate partners, each of which implements the WarehouseManager application. Each 'partner' is declared via an engine reference component.

  

Service Reference

A service reference component, which is modeled within the EOA specification by the ServiceReference class, is nested within its parent engine reference component. As depicted above, a service reference component references a service component defined on the referenced partner engine.

  

As shown within the runtime engine declaration, a service reference component provides a point where private policy with policy subject SERVICE can be attached. Note that if no policy is required, the <serviceReference> element can be omitted, unless the schema used to define the type specific engine defines an attribute that cannot be defaulted. If the element is omitted, a service reference component, along with its nested content, will be auto-generated for you.

Endpoint Reference

An endpoint reference component, which is modeled within the EOA specification by the EndpointReference class, is nested within its parent service reference component. As depicted above, an endpoint reference component references an endpoint component defined on the service referenced by the parent service reference component.

  

As shown within the runtime engine declaration, an endpoint reference component provides a point where private policy with policy subject ENDPOINT can be attached. Note that if no policy is required, the <endpointReference> element can be omitted, unless the schema used to define the type specific engine defines attributes that cannot be defaulted. If the element is omitted, an endpoint reference component, along with its nested content, will be auto-generated for you.

Endpoint Operation Reference

An endpoint operation reference component, which is modeled within the EOA specification by the EndpointOperationReference class, is nested within its parent endpoint reference component. As depicted above, an endpoint operation reference component references an endpoint operation component defined on the endpoint referenced by the parent endpoint reference component.

  

As shown within the runtime engine declaration, an operation reference component provides a point where private policy with policy subject OPERATION can be attached. Note that if no policy is required, the <operationReference> element can be omitted, unless the schema used to define the type specific engine defines attributes that cannot be defaulted. If the element is omitted, an operation reference component, along with its nested content, will be auto-generated for you.

Endpoint Action Reference

An endpoint action reference component, which is modeled within the EOA specification by the EndpointActionReference class, is nested within its parent operation reference component. An action reference component references an endpoint action component defined on the endpoint operation referenced by the parent endpoint reference component.

As depicted within the runtime engine declaration, an endpoint action reference component provides a point where private policy with policy subject MESSAGE can be attached. Note that if no policy is required, the <actionReference> element can be omitted, unless the schema used to define the type specific engine defines attributes that cannot be defaulted. If the element is omitted, an action reference component, will be auto-generated for you.

Policy Expressions

A policy expression provides runtime policy behavior one or more of which can be defined within a top-level policy component or which can be 'attached' to the EOA component model using one of three different policy attachment mechanisms. The policy expression component is modeled within the EOA specification by the PolicyExpression interface. A policy expression's behavior is defined as an extension to the core EOA specification. The examples below use version 1.5 of the WS-Policy specification. If you are unfamiliar with ws-policy, we recommend reading the ws-policy 1.5 primer. For a list of available policy implementations, please see the extension reference.

The sections that follow are intended to provide you with an understanding of how the various policy constructs, i.e. alternatives, subjects, vocabularies and assertions are organized, combined and manipulated within the context of alakai in order to enable and constrain the system's modulable features. In the discussions that follow, we'll assume you have a general understanding of the different policy 'operations' as well as an understanding of 'normal' vs. 'compact' form.

Policy Alternatives

A policy expression contains zero or more policy alternatives. A policy alternative defines a set of policy assertions, which, when taken as a whole, offer an 'alternative' choice to other policy alternatives defined within the context of the same parent expression. A policy alternative is modeled within the EOA specification by the PolicyAlternative interface. At least one alternative must be supported for the parent expression to be considered supported. Note that an expression with no alternatives indicates no permissible behavior.

Policy Assertions

Zero or more policy assertions can be defined within a policy alternative. A policy assertion is domain specific as indicated by its assertion type. An assertion type, as identified by its qualified name, is defined within a policy vocabulary namespace, which should be modeled via a schema. Each modulable feature is required to identify the vocabulary namespace which it 'understands' and which can be used to enable/constrain the feature. A listing of each modulable feature along with its policy vocabulary and usage examples can be found here. A policy assertion is modeled within the EOA specification by the PolicyAssertion interface.

Element Policy

The term element policy refers to a construct which aggregates policy expressions which are attached to an element within a component's xml representation, by merging them into a single expression, as demonstrated by the example below. Element policy is modeled within the EOA specification by the ElementPolicy class.

<deployment xmlns="http://bluestemsoftware.org/specification/eoa/1.0/deployment">
  <components>
    <wsdl:description xmlns:wsdl="http://www.w3.org/ns/wsdl" targetNamespace="http://foo" xmlns:tns="http://foo" xmlns:wsp="http://www.w3.org/ns/ws-policy">
      <wsdl:types>
        <xs:import namespace="http://mycompany.com"/>
      </wsdl:types>  
      <wsdl:interface name="myinterface" xmlns:ns01="http://mycompany.com">
        <wsdl:operation name="myoperation" pattern="http://www.w3.org/ns/wsdl/in-only">
          <wsdl:input element="ns01:myInputElement">
            <wsp:PolicyReference URI="#A" />
            <wsp:Policy>
              <wsp:ExactlyOne>
                <wsp:All>
                  <ns02:bar xmlns:ns02="http://ns02" />
                </wsp:All>
              </wsp:ExactlyOne>
            </wsp:Policy>
            <wsp:Policy>
              <wsp:ExactlyOne>
                <wsp:All>
                  <ns03:baz xmlns:ns03="http://ns03" do="this"/>
                </wsp:All>
                <wsp:All>
                  <ns03:baz xmlns:ns03="http://ns03" do="that"/>
                </wsp:All>
              </wsp:ExactlyOne>
            </wsp:Policy>
          </wsdl:input>
        </wsdl:operation>
      </wsdl:interface>
      <wsp:Policy wsu:Id="A" xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd">
        <wsp:ExactlyOne>
          <wsp:All>
            <ns01:foo xmlns:ns01="http://ns01" />
          </wsp:All>
        </wsp:ExactlyOne>
      </wsp:Policy>
    </wsdl:description>
  </components>
</deployment>    

The policy expressions which are 'attached' to the <wsdl:input> element defined above, are combined into a single merged expression which represents the nested action component's element policy. The merged and normalized expression depicted below, which represents the component's element policy, would be retrieved via the abstract action's getElementPolicy() method. Note that while you will never have to actually use the APIs which are demonstrated here, and within the sections below, the references should, however, help you to understand how each individual construct factors into the overall architecture.

<wsp:Policy xmlns:wsp="http://www.w3.org/ns/ws-policy">
  <wsp:ExactlyOne>
    <wsp:All>
      <ns01:foo xmlns:ns01="http://ns01"/>
      <ns02:bar xmlns:ns02="http://ns02"/>
      <ns03:baz do="this" xmlns:ns03="http://ns03"/>
    </wsp:All>
    <wsp:All>
      <ns01:foo xmlns:ns01="http://ns01"/>
      <ns02:bar xmlns:ns02="http://ns02"/>
      <ns03:baz do="that" xmlns:ns03="http://ns03"/>
    </wsp:All>
  </wsp:ExactlyOne>
</wsp:Policy>

Public Policy

The term public policy, within the EOA specification, collectively refers to the set of element policy attached to the static component model, i.e. it refers to all policy which is defined within the <components> element of an EOA deployment. It is deemed 'public' because it is considered to be a part of a component's 'public' description. Not all policy, however, is intended for 'public' consumption. Some, is instead considered 'private.'

Private Policy

The term private policy, within the EOA specification, collectively refers to the set of element policy attached to the runtime component model, i.e. it refers to all policy which is defined within the <providers> element of an EOA deployment. This is where you define policy which is not intended for 'public' consumption, i.e. policy which defines confidential assertions, e.g. user tokens, etc ... and/or policy which is to be intersected with 'public' policy, e.g. in order to assert an advertised policy alternative.

Effective Policy

The ws-policy specification defines four different policy 'subjects,' each of which is manifested within the EOA specification by the EffectivePolicy class. The point at which element policy is attached within the EOA component model, defines the policy subject. The effective policy's subject is indicated via the class's getPolicySubject() method. We'll examine the different types of effective policy, each of which defines a different policy subject.

Service Policy

The service policy object aggregates element policy with policy subject SERVICE. It is defined within the EOA specification by the ServicePolicy class. As depicted in the diagram below, 'public' service policy aggregates element policy attached to the service component while 'private' service policy aggregates policy attached to the service reference component.

  

Endpoint Policy

The endpoint policy object aggregates element policy with policy subject ENDPOINT. It is defined within the EOA specification by the EndpointPolicy class. As depicted in the diagram below, 'public' endpoint policy aggregates element policy attached to the endpoint component, binding component, and the interface component, while 'private' endpoint policy aggregates policy attached to the endpoint reference component.

  

Operation Policy

The operation policy object aggregates element policy with policy subject OPERATION. It is defined within the EOA specification by the OperationPolicy class. As depicted in the diagram below, 'public' operation policy aggregates element policy attached to the binding operation component and the interface operation component, while 'private' operation policy aggregates policy attached to the endpoint operation reference component.

  

Message Policy

The message policy object aggregates element policy with policy subject MESSAGE. It is defined within the EOA specification by the MessagePolicy class. As depicted in the diagram below, 'public' message policy aggregates element policy attached to the interface message component, interface fault component, interface action component, binding fault component and binding action component, while 'private' message policy aggregates policy attached to the endpoint action reference component. Note that element policy can only be attached to an interface message component within a WSDL 1.1 definition (which, by the way, isn't recommended.) Note also that if the action is a 'normal,' i.e. non-fault, action, then element policy which is attached to the fault components, if any, is excluded from the aggregation.

  

Action Policy

The action policy object serves to aggregate all four effective policy containers, i.e. one for each policy subject, each of which contain policy relevant to a specific 'action.' The term action, as it is used here, refers to a 'cross cutting' concern, i.e. which manifests itself across all three layers of the system as depicted within the system layers diagram. The various components used to model an action, each of which describe the action from a different perspective are the endpoint action reference component, endpoint action component, binding action component and the interface action component.

Keep in mind, that each of the above components are nested within a component hierarchy. An action policy instance therefore incorporates policy from all parent components as well, as depicted within the diagrams below. The action policy object is modeled within the EOA specification by the ActionPolicy class. Action policy is further classified according to whether it contains public policy or private policy as previously discussed. Action policy is used to enable and/or constrain modulable features.

  

  

Monolithic Features

Monolithic is the term used to describe any feature that it is manifested as a single unit of functionality, which is retrieved from server and whose type specific API is used programmatically within your extensions, e.g. the HTTPClientFeature demonstrated above. A list of the available monolithic features categorized by feature type, along with configuration examples and code snippets can be found within the features reference.

Modulable Features

While a modulable feature may also provide monolithic type functionality, it typically manifests its behavior on a per message basis, i.e. via feature modules. This type of feature is modeled within the EOA specification by the ModulableFeature interface. Before we discuss each specific module type, another abstraction is warranted, i.e. one which should help you better understand the distributed nature of modulable feature processing.

System Layers

The layer within which a message is processed depends upon the type of feature implemented by the feature module. If you conceptualize the system from the perspective of a message, it might look like the somewhat colorful onion depicted below, i.e. a message travels through three different layers on it's way into an application and then through the same three layers in reverse on its way out of an application, i.e. as a new message instance, e.g.

System Layers

Transport modules, which implement transport feature behavior, process messages within the transport layer. When a message passes through the transport layer, its content is opaque, i.e. a transport module's behavior is solely affected by transport protocol specific headers, e.g. http headers.

Binding modules, which implement binding feature behavior, process messages within the binding layer. When a message passes through the binding layer, its payload is opaque, i.e. a binding module's behavior is primarily affected by messaging protocol specific headers, e.g. soap headers.

Application modules, which implement application feature behavior, process messages within the application layer. When a message passes through the application layer, the protocol headers are opaque, i.e. an application module's behavior is primarily concerned with a message's payload.

Action Specific

While a common configuration for the modulable feature can be defined within the server.xml file, as discussed within the section on enabling features, its modules are enabled/constrained via action policy, i.e. by policy attached to various points within the runtime and static engine component model. When enabled, a feature module is installed on an endpoint action reference component as depicted below.

A module's configuration, as defined via its action policy, is specific to that module and affects message processing for the referenced action only, as depicted above. When a feature module is created by its parent feature, and 'installed' on an action reference component, the feature uses public action policy and private action policy, both of which have been filtered by alakai to contain only those policy assertions defined within a vocabulary understood by the feature, to configure the module.

Note that binding modules and application modules are invoked by a binding/engine according to the module's relative order which is defined as an attribute on the module instance. If the order in which a module should be processed is relevant, i.e. if the feature is not 'natively implemented' by the binding/engine and the feature defines a dependency on another feature, the module should specify a relative value. Module processing is ordered from the least relative value to the greatest relative value. If a module is to be the first module within the processing chain, the relative value java.lang.Short.MIN_VALUE should be returned. If the module is to be the last module within the processing chain, the relative value java.lang.Short.MAX_VALUE should be returned. If processing order is irrelevant, the relative value 0 SHOULD be returned. If relevant, the parent feature should provide the ability to configure the module's relative order via private policy.

Transport Modules

A transport module is modeled within the EOA specification by the TransportModule class. It implements transport feature behavior on a per message basis, i.e. by transporting the message into and out-of the binding layer. Note that each referenced action, as depicted in the diagram above, defines a single transport module. A list of the available transport features, along with example policy configurations can be found here.

Unlike binding modules and application modules which must be explicitly enabled via policy, alakai will, by default, as required by the EOA specification, enable a default transport module which uses the transport protocol employed by the binding used by the referenced endpoint, e.g. HTTP. The module will use the feature's default configuration, which using the HTTPTransportFeature as an example, configures a non-authenticating servlet to handle in-bound messages and a non-authenticating client to send out-bound messages.

Binding Modules

A binding module is modeled within the EOA specification by the BindingModule class. It implements binding feature behavior on a per message basis, i.e. by processing messaging protocol specific headers, e.g. SOAP headers. All of the ws-* features are implemented via binding modules. Binding modules must be explicitly enabled via policy. A list of the available binding features, along with example policy configurations can be found here.

Application Modules

An application module is modeled within the EOA specification by the ApplicationModule class. It implements application feature behavior on a per message basis, i.e. by processing the message payload. Some examples of functionality which might be implemented by an application module include logging, content transformation, etc... Application modules must be explicitly enabled via policy. A list of the available application features, along with example policy configurations can be found here.