Hi, as promised I transfered the post from Stephan in xdocs. It was easy, because the orginal post was very good and therefore it was more copy and paste :). I fixed hopefully) some typos and grammer.
I attached it as patch, cause I thought some of you folks want to review it. Any suggestios or extensions are welcomed... Cheers Gerhard PS: Stephen I put you as author in the xdoc with your email address. I hope this was Ok. -------------------------------------------- black holes are when GOD is dividing by zero --------------------------------------------
docpatch.diff
Description: Binary data
<?xml version="1.0"?>
<!DOCTYPE document SYSTEM "dtd/document-v10.dtd">
<document>
<header>
<title>Example Configuration</title>
<authors>
<person name="Stephen McConnell" email="[EMAIL PROTECTED]"/>
<person name="Gerhard Froehlich" email="[EMAIL PROTECTED]"/>
</authors>
</header>
<body>
<s1 title="Introduction">
<p>This example was originally a Mailing List response to a
some user questions!</p>
<p>The orginal post was written by Stephen McConnell.</p>
</s1>
<s1 title="The example">
<p>First we start with a <code>.xinfo</code> file for a
reasonably simple block that serves as a factory for business
processes to handle PKI certification requests:</p>
<source><![CDATA[
<?xml version="1.0"?>
<blockinfo>
<block>
<version>1.0</version>
</block>
<services>
<!--
This block could be declaring several services that it supports.
Unlike a Java interface, the service includes a version tag. So
it's possible for a block to have several services with possibly
different versions. If there are multiple services then just
declare them with multiple service entries here. Phoenix will make
sure that the class with the same name as the .xinfo file
implements these interfaces (if it doesn't then Phoenix will
terminate).
-->
<service name="org.apache.acme.hub.gateway.FactoryService" version="1.0" />
</services>
<!--
So far, we have the definition of a class that supports possibly
multiple version interfaces. But things get much more interesting, when
we think about the services that this block requires in order to function
properly. That's partly handled by the dependencies element and partly by
the assembly.xml file (which I'll explain later). In the following
dependency example there are seven "service" dependencies (i.e. 7 versioned
interface dependencies that must be fulfilled for this block to function.
-->
<dependencies>
<!--
Each dependency contains a declaration of a role name and a service
interface and a version that can fulfil that role. The dependency
does not say anything about where that service implementation should
come from (that's the job the assembly.xml file). The role element
is simply the label used in the implementation of your block configure
method that distinguishes a particular instance of the service.
-->
<dependency>
<role>GATEWAY</role>
<service name="org.apache.acme.hub.gateway.GatewayContext" version="1.0"/>
</dependency>
<!--
This dependency declaration simply states that in order to function,
this block requires a <service/> (in this case a wrapper to a CORBA
ORB version 2.4) and that the block implementation will lookup this
service using the "ORB" keyword.
-->
<dependency>
<role>ORB</role>
<service name="org.apache.acme.hub.gateway.ORBService" version="2.4"/>
</dependency>
<!--
This dependency declares a requirement for a PSS (Persistent State
Service) Storage Home.
-->
<dependency>
<role>PSS</role>
<service name="org.apache.acme.hub.gateway.ProcessorStorageHomeService" version="1.0"/>
</dependency>
<!--
This dependency enables the block to establish a call-back to the
block supplying the service. This block uses the Registry interface
to publish a business process description to a higher level manager.
-->
<dependency>
<role>REGISTRY</role>
<service name="org.apache.acme.hub.gateway.Registry" version="1.0"/>
</dependency>
<!-- etc. -->
<dependency>
<role>DOMAIN</role>
<service name="org.apache.acme.hub.gateway.DomainService" version="1.0"/>
</dependency>
<dependency>
<role>RANDOM</role>
<service name="org.apache.acme.hub.gateway.RandomService" version="1.0"/>
</dependency>
<dependency>
<role>CLOCK</role>
<service name="org.apache.acme.service.time.TimeService" version="1.0"/>
</dependency>
</dependencies>
</blockinfo>
]]>
</source>
<p>Next is the block declaration, which is cut from an <code>assembly.xml</code>
file. This enables the declaration of WHERE the services are coming from.
I.e. you may have a system with many blocks and even the potential for matching
services available from more that one block. The class attribute provides the
link to the <code>.xinfo</code> file and the implementation class. The name
is used a key within the assembly.xml file when wiring things together.
E.g. the provide element references a block by its name - and declares that the
named block will serve as the provider of the service. The role attribute matches
the role element in the <code>.xinfo</code> dependency declaration.</p>
<source><![CDATA[
<?xml version="1.0"?>
<assembly>
<!-- Certification Request Factory -->
<block class="org.apache.acme.pki.process.CertificationRequestServer" name="certification" >
<provide name="gateway" role="GATEWAY"/>
<provide name="gateway" role="ORB"/>
<provide name="gateway" role="PSS"/>
<provide name="gateway" role="DOMAIN"/>
<provide name="gateway" role="RANDOM"/>
<provide name="pki" role="REGISTRY"/>
<provide name="time" role="CLOCK"/>
</block>
</assembly>
]]>
</source>
<s1/>
<s1 title="Why this seperation?"/>
<ul>
<li>It forces structure and separation</li>
<li>It provides a way of managing possibly multiple versions of the
same interface in a single environment</li>
<li>It enables explicit declaration of the source of service provision</li>
</ul>
<p>For example you can have multiple blocks providing a TimeService.
One of those blocks uses an external time reference while the others
use a local time reference. The local time block
declare dependencies on the external source time block and is periodically
synchronised. In this example all of the TimeService services are exposing
the same interface, same version (i.e. same service), but the decision as to
which service is the provider to another can be explicitly controlled.
While the time example is perhaps trivial, there are significant policy
security implications related to service provider selection.</p>
</s1>
</body>
<footer>
<legal>
Copyright (c) @year@ The Jakarta Apache Project All rights reserved.
$Revision: 1.4 $ $Date: 2001/11/10 21:03:57 $
</legal>
</footer>
</document>
-- To unsubscribe, e-mail: <mailto:[EMAIL PROTECTED]> For additional commands, e-mail: <mailto:[EMAIL PROTECTED]>
