[jboss-cvs] JBossAS SVN: r67116 - in projects/microcontainer/trunk/docs/User_Guide: en-US and 8 other directories.
jboss-cvs-commits at lists.jboss.org
jboss-cvs-commits at lists.jboss.org
Thu Nov 15 03:55:34 EST 2007
Author: newtonm
Date: 2007-11-15 03:55:33 -0500 (Thu, 15 Nov 2007)
New Revision: 67116
Added:
projects/microcontainer/trunk/docs/User_Guide/src/
projects/microcontainer/trunk/docs/User_Guide/src/main/
projects/microcontainer/trunk/docs/User_Guide/src/main/css/
projects/microcontainer/trunk/docs/User_Guide/src/main/css/css/
projects/microcontainer/trunk/docs/User_Guide/src/main/css/css/dirty.css
projects/microcontainer/trunk/docs/User_Guide/src/main/css/css/docnav.css
projects/microcontainer/trunk/docs/User_Guide/src/main/css/css/documentation.css
projects/microcontainer/trunk/docs/User_Guide/src/main/css/css/reports.css
projects/microcontainer/trunk/docs/User_Guide/src/main/css/css/rhel.css
projects/microcontainer/trunk/docs/User_Guide/src/main/docbook/
projects/microcontainer/trunk/docs/User_Guide/src/main/docbook/Author_Group.xml
projects/microcontainer/trunk/docs/User_Guide/src/main/docbook/Legal_Notice.xml
projects/microcontainer/trunk/docs/User_Guide/src/main/docbook/User_Guide.xml
projects/microcontainer/trunk/docs/User_Guide/src/main/images/
projects/microcontainer/trunk/docs/User_Guide/src/main/images/images/
projects/microcontainer/trunk/docs/User_Guide/src/main/images/images/caution.png
projects/microcontainer/trunk/docs/User_Guide/src/main/images/images/documentation.png
projects/microcontainer/trunk/docs/User_Guide/src/main/images/images/dot.png
projects/microcontainer/trunk/docs/User_Guide/src/main/images/images/dot2.png
projects/microcontainer/trunk/docs/User_Guide/src/main/images/images/important.png
projects/microcontainer/trunk/docs/User_Guide/src/main/images/images/note.png
projects/microcontainer/trunk/docs/User_Guide/src/main/images/images/red-bg.png
projects/microcontainer/trunk/docs/User_Guide/src/main/images/images/rhlogo.png
projects/microcontainer/trunk/docs/User_Guide/src/main/images/images/shine.png
projects/microcontainer/trunk/docs/User_Guide/src/main/images/images/stock-go-back.png
projects/microcontainer/trunk/docs/User_Guide/src/main/images/images/stock-go-forward.png
projects/microcontainer/trunk/docs/User_Guide/src/main/images/images/stock-go-up.png
projects/microcontainer/trunk/docs/User_Guide/src/main/images/images/stock-home.png
projects/microcontainer/trunk/docs/User_Guide/src/main/images/images/tip.png
projects/microcontainer/trunk/docs/User_Guide/src/main/images/images/warning.png
projects/microcontainer/trunk/docs/User_Guide/src/main/images/images/watermark-alpha1.png
projects/microcontainer/trunk/docs/User_Guide/src/main/images/images/watermark-alpha2.png
projects/microcontainer/trunk/docs/User_Guide/src/main/images/images/watermark-beta1.png
projects/microcontainer/trunk/docs/User_Guide/src/main/images/images/watermark-beta2.png
projects/microcontainer/trunk/docs/User_Guide/src/main/images/images/watermark-pre-release-candidate.png
projects/microcontainer/trunk/docs/User_Guide/src/main/images/images/watermark-release-candidate.png
projects/microcontainer/trunk/docs/User_Guide/src/main/xsl/
projects/microcontainer/trunk/docs/User_Guide/src/main/xsl/main-html.xsl
projects/microcontainer/trunk/docs/User_Guide/src/main/xsl/redhat.xsl
projects/microcontainer/trunk/docs/User_Guide/src/main/xsl/xhtml-common.xsl
Removed:
projects/microcontainer/trunk/docs/User_Guide/en-US/Author_Group.xml
projects/microcontainer/trunk/docs/User_Guide/en-US/Legal_Notice.xml
projects/microcontainer/trunk/docs/User_Guide/en-US/User_Guide.xml
Modified:
projects/microcontainer/trunk/docs/User_Guide/pom.xml
Log:
Added Red Hat styling for HTML.
Deleted: projects/microcontainer/trunk/docs/User_Guide/en-US/Author_Group.xml
===================================================================
--- projects/microcontainer/trunk/docs/User_Guide/en-US/Author_Group.xml 2007-11-15 08:03:23 UTC (rev 67115)
+++ projects/microcontainer/trunk/docs/User_Guide/en-US/Author_Group.xml 2007-11-15 08:55:33 UTC (rev 67116)
@@ -1,7 +0,0 @@
-<?xml version='1.0' encoding='UTF-8'?>
-<!DOCTYPE authorgroup PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
-]>
-<authorgroup>
- <corpauthor>Mark Newton</corpauthor>
- <corpauthor>Aleš Justin</corpauthor>
-</authorgroup>
Deleted: projects/microcontainer/trunk/docs/User_Guide/en-US/Legal_Notice.xml
===================================================================
--- projects/microcontainer/trunk/docs/User_Guide/en-US/Legal_Notice.xml 2007-11-15 08:03:23 UTC (rev 67115)
+++ projects/microcontainer/trunk/docs/User_Guide/en-US/Legal_Notice.xml 2007-11-15 08:55:33 UTC (rev 67116)
@@ -1,17 +0,0 @@
-<?xml version='1.0'?>
-<!DOCTYPE legalnotice PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
-]>
-
-<legalnotice id="Book-Legal_Notice">
- <title>Legal Notice</title>
- <para>
- <address>
- <street>1801 Varsity Drive</street>
- <city>Raleigh</city>, <state>NC</state><postcode>27606-2072</postcode><country>USA</country><phone>Phone: +1 919 754 3700</phone>
- <phone>Phone: 888 733 4281</phone>
- <fax>Fax: +1 919 754 3701</fax>
- <pob>PO Box 13588</pob><city>Research Triangle Park</city>, <state>NC</state><postcode>27709</postcode><country>USA</country>
- </address>
- </para>
-</legalnotice>
-
Deleted: projects/microcontainer/trunk/docs/User_Guide/en-US/User_Guide.xml
===================================================================
--- projects/microcontainer/trunk/docs/User_Guide/en-US/User_Guide.xml 2007-11-15 08:03:23 UTC (rev 67115)
+++ projects/microcontainer/trunk/docs/User_Guide/en-US/User_Guide.xml 2007-11-15 08:55:33 UTC (rev 67116)
@@ -1,421 +0,0 @@
-<?xml version='1.0' encoding='UTF-8'?>
-<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN" "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd" [
-<!ENTITY % RH-ENTITIES SYSTEM "Common_Config/rh-entities.ent">
-]>
-<book>
- <bookinfo>
- <title>JBoss Microcontainer 2.0.0</title>
- <subtitle>User Guide</subtitle>
- <issuenum>2.0</issuenum>
- <productnumber>2</productnumber>
- <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Author_Group.xml"/>
- <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Legal_Notice.xml"/>
- </bookinfo>
- <preface>
- <title>What this Book Covers</title>
- <para>This book aims to help you become familiar with JBoss Microcontainer in order that you can use it to develop your own services or applications.</para>
- <para>Part I 'Getting Started' introduces the technology and explains how it relates to Java development in general. It then goes on to cover a complete use-case so that you can quickly see how the microcontainer works in real-life.</para>
- <para>Part II 'POJO Development' takes a look at the various methods you can use to construct POJOs and wire them together using injections together with other features.</para>
- <para>Part III 'AOP Development' goes on to look at how you can add behaviour to your POJOs using Aspects and covers the various ways this can be done.</para>
- <para> Part IV 'Extending the Microcontainer' shows how you can write your own extensions by creating new dependencies and gives some examples of how this has already been done.</para>
- <para>Part V 'Integrating the Microcontainer' covers how the microcontainer is used in JBoss AS 5 as the integration technology for the various services and core infrastructure. We also look at how legacy services, developed using MBeans, remain compatible with the new microcontainer and see how it is possible to manage POJO services at runtime.</para>
- </preface>
- <part>
- <title>Getting Started</title>
- <chapter id="overview">
- <title>Introduction</title>
- <para>The Java platform has traditionally been distributed in 3 editions, each providing a different type of runtime environment: </para>
- <itemizedlist>
- <listitem>
- <para>Java ME (Micro Edition) - Mobile or other embedded devices</para>
- </listitem>
- <listitem>
- <para>Java SE (Standard Edition) - Desktop machines or servers (typically running 2-tier applications)</para>
- </listitem>
- <listitem>
- <para>Java EE (Enterprise Edition) - Servers (typically running 3-tier applications)</para>
- </listitem>
- </itemizedlist>
- <para>Each environment aims to provide a base level of functionality on top of which developers can add their own code to create applications. For example Java SE provides networking and security libraries together with graphical user interface toolkits to facilitate the development of desktop and simple client-server applications. Java EE takes this a stage further by adding a number of 'enterprise' services such as transactions, messaging, and persistence that allow much more robust and scalable 'enterprise' applications to be developed. These services are typically combined together inside a JEE application server to provide a standard runtime environment for enterprise applications but there are often occasions when some services are never used.</para>
- <para>Having unused services in your environment is undesirable as they can take up valuable resources such as CPU and memory. They can also clutter up the environment with unnecessary configuration files, complicating maintenance and adding unnecessary complexity. It would be better if there was a controlled way to remove such services without breaking any dependencies they might have. Similarly there are often occasions when applications need services that aren't provided by JEE so it would be better if there was a controlled way to add them, again making sure that any dependencies were first satisfied.</para>
- <para>JBoss Microcontainer aims to provide these capabilities by allowing services, created using Plain Old Java Objects (POJOs), to be deployed into a standard Java SE runtime environment in a controlled manner to create a customized environment for your applications. Dependencies between services are fully managed by the microcontainer to ensure that new services cannot be deployed until services they depend on have first been deployed. Likewise undeploying a service causes all dependent services to first be undeployed in order to maintain the integrity of the system. </para>
- <para>Deploying services in this way, on top of a Java SE environment, is exactly how we have created the latest version of JBoss Application Server (JBoss AS 5.0) which provides a standard Java EE environment. If you need additional services then you can simply deploy these on top of Java EE to provide the functionality you need. This even applies when using the microcontainer in different Java EE environments such as Glassfish since you can plug in different classloading models during the service deployment phase.</para>
- <para>Since JBoss Microcontainer is very lightweight and deals with POJOs it can also be used to deploy services into a Java ME runtime environment. This opens us new possibilities for mobile applications that can now take advantage of enterprise services without requiring a full JEE application server. </para>
- <para>In common with other lightweight containers JBoss Microcontainer uses dependency injection to wire individual POJOs together to create services. Configuration is performed using either XML or annotations depending on where the information is best located. Finally unit testing is made extremely simple thanks to a helper class that extends JUnit to setup the test environment, allowing you to access POJOs and services from your test methods using just a few lines of code.</para>
- </chapter>
- <chapter>
- <title>Download and Installing</title>
- <para>JBoss Microcontainer 2.0.0 is currently only available as a beta release via Maven2. This means that you need to install and configure Maven before you can begin development. Once this is done then you can create a maven project that depends on the JBoss Microcontainer JARs in order to download and install them into your local maven repository. You can then create an assembly for your final application in order to package the relevant JARs into a distributable format.</para>
- <para>The examples created for this User Guide use Maven2 to achieve exactly this so it is highly recommended that you <ulink url="http://labs.jboss.com/file-access/default/members/jbossmc/downloads/userGuide-examples-13112007.zip">download</ulink> these first and take a look at how they work.</para>
- <note>
- <para>To build and run the examples you first need to install and configure Maven 2.0.7 available from <ulink url="http://maven.apache.org/">http://maven.apache.org/</ulink></para>
- </note>
- <para>Installation is performed by downloading and unzipping the maven-2.0.7-bin.zip file to a convenient location on your local disk. Configuration consists of adding $MAVEN_HOME/bin to your path and adding the following profile to your ~/.m2/settings.xml file:</para>
- <para><programlisting><settings>
- <profiles>
- <profile>
- <id>jboss.repository</id>
- <activation>
- <property>
- <name>!jboss.repository.off</name>
- </property>
- </activation>
- <repositories>
- <repository>
- <id>snapshots.jboss.org</id>
- <url>http://snapshots.jboss.org/maven2</url>
- <snapshots>
- <enabled>true</enabled>
- </snapshots>
- </repository>
- <repository>
- <id>repository.jboss.org</id>
- <url>http://repository.jboss.org/maven2</url>
- <snapshots>
- <enabled>false</enabled>
- </snapshots>
- </repository>
- </repositories>
- <pluginRepositories>
- <pluginRepository>
- <id>repository.jboss.org</id>
- <url>http://repository.jboss.org/maven2</url>
- <snapshots>
- <enabled>false</enabled>
- </snapshots>
- </pluginRepository>
- <pluginRepository>
- <id>snapshots.jboss.org</id>
- <url>http://snapshots.jboss.org/maven2</url>
- <snapshots>
- <enabled>true</enabled>
- </snapshots>
- </pluginRepository>
- </pluginRepositories>
- </profile>
- </profiles>
-</settings></programlisting></para>
- <para>This profile informs maven of the two JBoss repositories (snapshots and releases) that are needed to download the JBoss Microcontainer and dependant JARs.</para>
- <para>Once you have configured Maven and downloaded the examples then you can go to one of the following directories in the <code>examples/User_Guide</code> directory and enter <code>mvn install</code> to perform a build:</para>
- <para/>
- <itemizedlist>
- <listitem>
- <para>gettingStarted - projects for creating and using a service together with AOP</para>
- </listitem>
- <listitem>
- <para>pojoDevelopment - examples of creating and configuring POJOs using XML and Annotations</para>
- </listitem>
- <listitem>
- <para>aopDevelopment - examples of using AOP to add behaviour to POJOs</para>
- </listitem>
- <listitem>
- <para>extending - examples of how we have created various extensions to the core microcontainer by creating new dependencies</para>
- </listitem>
- <listitem>
- <para>integrating - examples of how the microcontainer forms the basis of JBoss AS 5 and how you can deploy MBean services alongside POJO services for backwards compatibility</para>
- </listitem>
- </itemizedlist>
- <para>Instructions on how to run the individual examples can be found in the relevant parts of this guide.</para>
- </chapter>
- <chapter>
- <title>Building services</title>
- <para><emphasis role="bold">
- <emphasis role="underline">POJOs</emphasis>
- </emphasis></para>
- <para>The term POJO is an acronym for Plain Old Java Object and was first coined while Rebecca Parsons, Josh MacKenzie, and Martin Fowler were preparing for a talk at a conference in September 2000. It describes the practice of encoding business logic in regular java objects instead of components such as EJB 2.1 Entity Beans. The benefit of this approach is that you're not required to implement any special interfaces. This not only keeps your code simple but allows it to be used in a wider variety of environments and makes it easy to unit test.</para>
- <para><emphasis role="bold">Definition:</emphasis> <emphasis role="italic">A POJO declares business methods, which define behaviour, and properties, which represent state. Some properties represent associations to other POJOs.</emphasis></para>
- <para>For experienced developers this should sound familiar as it mimicks almost exactly the proposals set out in the JavaBeans specification. JavaBeans describes a component model for User Interface development emphasizing simplicity and standardized naming conventions for property accessor methods. The idea was that this would allow automatic discovery of an object's properties so that an instance could easily be created and populated with state at runtime. The main use case was creating and configuring visual user interface components such as text boxes, buttons, and tables from within an integrated development environment (IDE).</para>
- <para><emphasis role="bold">Definition:</emphasis> <emphasis role="italic">A Java Bean is a reusable software component that can be manipulated visually in a builder tool.</emphasis></para>
- <para> Importantly a Java Bean is not required to inherit from any particular base class or interface. Also while Java Beans are primarily targeted at builder tools they are entirely usable by human programmers with conventional text editors.</para>
- <para>Strictly speaking a Java Bean should include support for events and persistence but in many cases developers choose not to implement these features and simply follow the standardized naming conventions for property accessor methods; i.e. get and set. This 'lightweight' form of Java Bean is commonly referred to as simply a 'bean' and is semantically equivalent to a POJO.</para>
- <para>The terms POJO and bean are therefore interchangeable and you will encounter both in the microcontainer documentation and configuration files.</para>
- <para><emphasis role="bold">
- <emphasis role="underline">Services</emphasis>
- </emphasis></para>
- <para>The word 'service' has many definitions in the English language but in the context of developing Java applications it is helpful to define it as follows:</para>
- <orderedlist>
- <listitem>
- <para>A service should perform work that is useful to multiple clients, thereby preventing each client from having to perform the work themselves.</para>
- </listitem>
- <listitem>
- <para>A service should have a name that clients can lookup at runtime to gain access. This provides a standard way to access different kinds of services and removes the need for clients to explicitly create services before they can be used. </para>
- </listitem>
- <listitem>
- <para>Internal changes to a service should not affect any clients. In practice this means that clients should access a service using a well defined interface so that the service implementation can be changed without having to recompile any clients. </para>
- </listitem>
- </orderedlist>
- <para>Using this definition we can now answer some simple questions:</para>
- <para>Q) Is a POJO a service?</para>
- <para>A) No, because although it performs work that is useful to multiple clients you cannot access it using a name. Clients have to create a POJO themselves either directly using the <code>new</code> operator or indirectly using a factory. </para>
- <para>Q) Does a class have to implement an interface in order to provide a 'well-defined' interface?</para>
- <para>A) Not necessarily. Providing that we don't remove fields or methods from a class, or restrict access to them, then we can always change its implementation without needing to recompile the client. See the section entitled <ulink url="http://java.sun.com/docs/books/jls/second_edition/html/execution.doc.html#44524">Resolution of Symbolic References</ulink> from the Java Language Specification for more details:</para>
- <para>The 'well-defined' interface in this respect is composed from the original class's fields and method signatures together with their access modifiers.</para>
- <note>
- <para>Implementing an interface is only necessary if we want to allow a client to <emphasis role="bold">choose</emphasis> between <emphasis role="bold">alternative implementations</emphasis>. i.e. if the client is compiled against an interface then we can provide as many different implementations of the interface as we like without having to recompile the client.</para>
- </note>
- <para>What then must we do in order to create a service using a POJO? The answer is to provide a naming mechanism that allows us to register a reference to the POJO instance with a name. Clients can then lookup the POJO reference using the name at runtime and use it to perform work. The POJO class is not required to implement an interface unless it is important that the client can choose between alternative implementations. </para>
- <para>JBoss Microcontainer provides such a naming mechanism in order that we can deploy our POJO services into a runtime environment such as Java SE and look them up from within our applications.</para>
- <para>Since robust implementations of Java EE services are already available from JBoss.org and other communities, it is common for companies to focus on creating more 'business-oriented' services. For this reason we shall look at creating, configuring and testing a simple Human Resources service that could potentially be used in a wide-variety of companies.</para>
- <section>
- <title>Creating POJOs</title>
- <para>The example that relates to this section can be found in the <code>examples/User_Guide/gettingStarted/humanResourcesService</code> directory. The directory layout, as with all of the examples for this User Guide, follows the <ulink url="http://maven.apache.org/guides/introduction/introduction-to-the-standard-directory-layout.html">Maven Standard Directory Layout</ulink>.</para>
- <para><programlisting>humanResourcesService/pom.xml
- /src/main/java
- /test/java
- /test/resources</programlisting></para>
- <para>Java source files are located in packages beneath the src/main/java directory:</para>
- <para><programlisting>org/jboss/example/service/Address.java
- /Employee.java
- /HRManager.java
-
-org/jboss/example/service/util/SalaryStrategy.java
- /AgeBasedSalaryStrategy.java
- /LocationBasedSalaryStrategy.java</programlisting></para>
- <para>As you can see from looking at the source code, each of these classes represents a simple POJO that doesn't implement any special interfaces. The most important class is HRManager as this represents the service entry point and therefore provides all of the public methods that clients will call.</para>
- <para/>
- <itemizedlist>
- <listitem>
- <para>addEmployee(Employee employee)</para>
- </listitem>
- <listitem>
- <para>getEmployees()</para>
- </listitem>
- <listitem>
- <para>getEmployee(String firstName, String lastName)</para>
- </listitem>
- <listitem>
- <para>removeEmployee(Employee employee)</para>
- </listitem>
- <listitem>
- <para>getSalary(Employee employee)</para>
- </listitem>
- <listitem>
- <para>setSalary(Employee employee, Integer newSalary)</para>
- </listitem>
- <listitem>
- <para>isHiringFreeze()</para>
- </listitem>
- <listitem>
- <para>setHiringFreeze(boolean hiringFreeze)</para>
- </listitem>
- <listitem>
- <para>getSalaryStrategy()</para>
- </listitem>
- <listitem>
- <para>setSalaryStrategy(SalaryStrategy strategy)</para>
- </listitem>
- </itemizedlist>
- <para>The Human Resources Service is therefore composed of the above 6 classes which work together to allow a list of employees, together with details of their addresses and salaries, to be maintained by an HRManger. In addition it is possible to configure HRManager so that different salary strategies are used. These place minimum and maximum limits on the salaries that can be awarded to employees depending on various rules.</para>
- <para>To compile the source code you simply need to enter <code>mvn compile</code> from the <code>humanResourcesService/</code> directory. This will create a new directory called <code>target/classes</code> containing the compiled code. To clean up the humanResourcesService project and remove the <code>target</code> directory simply enter <code>mvn clean</code>. </para>
- <para>Now that we have compiled our POJO classes we need to determine how to create instances of them. This is done by creating an XML deployment descriptor that contains a list of beans representing individual instances. Each bean is given a name so that the instance can be looked up at runtime by clients.</para>
- <programlisting><?xml version="1.0" encoding="UTF-8"?>
-
-<deployment xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
- xsi:schemaLocation="urn:jboss:bean-deployer:2.0 bean-deployer_2_0.xsd"
- xmlns="urn:jboss:bean-deployer:2.0">
-
- <bean name="HRService" class="org.jboss.example.service.HRManager"/>
-
-</deployment></programlisting>
- <para>Here we have declared that we want to create an instance of the HRManager class and register it with the name HRService. This file is passed to a deployer associated with the microcontainer at runtime which performs the actual deployment and instantiates the beans.</para>
- </section>
- <section>
- <title>Wiring POJOs together </title>
- <para>So far we have seen how to create POJOs and declare instances of them together with names in the XML deployment descriptor. However, individual POJO instances can only provide relatively simple behaviour. Things really get interesting when we combine POJOs together to perform more complex tasks. In our example we know that we can choose a number of different salary strategies for the HRManager so how do we go about wiring the POJOs together?</para>
- <para>The answer is to use the XML deployment descriptor again as follows:</para>
- <programlisting><?xml version="1.0" encoding="UTF-8"?>
-
-<deployment xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
- xsi:schemaLocation="urn:jboss:bean-deployer:2.0 bean-deployer_2_0.xsd"
- xmlns="urn:jboss:bean-deployer:2.0">
-
- <bean name="HRService" class="org.jboss.example.service.HRManager">
- <property name="salaryStrategy"><inject bean="AgeBasedSalary"/></property>
- </bean>
-
- <bean name="AgeBasedSalary"
- class="org.jboss.example.service.util.AgeBasedSalaryStrategy"/>
-
-</deployment></programlisting>
- <para>We first need to create an instance of our chosen salary strategy by including an additional <bean> element. Here we have chosen the AgeBasedSalaryStrategy. Next we need to inject a reference to this bean into the instance of HRManager created using the HRService bean. Injection is possible as the HRManager class contains a <code>setSalaryStrategy(SalaryStrategy strategy)</code> method. Behind the scenes JBoss Microcontainer will call this method on the newly created HRManager instance and pass in a reference to the AgeBasedSalaryStrategy instance.</para>
- <para>In other words the XML deployment descriptor causes the same sequence of events to occur as if you had written the following code:</para>
- <programlisting>HRManager hrService = new HRManager();
-AgeBasedSalaryStrategy ageBasedSalary = new AgeBasedSalaryStrategy();
-hrService.setSalaryStrategy(ageBasedSalary);</programlisting>
- <para>In addition to performing injection via property setter methods JBoss Microcontainer can also perform injection via constructor parameters if necessary. For more details please see the 'Injection' chapter in Part II 'POJO Development'. </para>
- <note>
- <para>Although we can create instances of our classes using the <bean> element in the deployment descriptor it is not always appropriate to do so. For example we do not need to create instances of the Employee and Address classes since these will be created by the client. As such they remain part of the service but are not mentioned in the deployment descriptor. </para>
- <para>Also note that it is possible to define multiple beans within a deployment descriptor provided that each has a unique name. These names are required in order to perform injection as shown above. This does not mean to say however that all of these beans represent services. While a service could be implemented using a single bean it is most often the case that multiple beans are used together as in our example. In these cases there is usually one bean that represents the service entry point containing the public methods intended for the clients to call. In our example this is the HRService bean. Notice that there is nothing in the XML deployment descriptor to say which beans represent a service or indeed which bean if any is the service entry point. Care must therefore be taken when creating deployment descriptors to ensure that sufficient comments are included to describe what the beans are used for. Alternatively a naming convention such as ending each be!
an name that represents a service entry point with 'Service', i.e. HRService can be used instead.</para>
- </note>
- </section>
- <section>
- <title>Configuring a service</title>
- <para>Injecting references between POJO instances is one way of configuring a service however we can also inject values into POJO properties. The following deployment descriptor shows how we can configure the HRManager instance to have a hiring freeze and the AgeBasedSalaryStrategy to have new minimum and maximum salary values:</para>
- <programlisting><?xml version="1.0" encoding="UTF-8"?>
-
-<deployment xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
- xsi:schemaLocation="urn:jboss:bean-deployer:2.0 bean-deployer_2_0.xsd"
- xmlns="urn:jboss:bean-deployer:2.0">
-
- <bean name="HRService" class="org.jboss.example.service.HRManager">
- <property name="hiringFreeze">false</property>
- <property name="salaryStrategy"><inject bean="AgeBasedSalary"/></property>
- </bean>
-
- <bean name="AgeBasedSalary" class="org.jboss.example.service.util.AgeBasedSalaryStrategy">
- <property name="minSalary">1000</property>
- <property name="maxSalary">80000</property>
- </bean>
-
-</deployment></programlisting>
- <para>As with wiring POJOs together the classes need to have public setter methods for the relevant properties so that values can be injected. For example the HRManager class has a <code>setHiringFreeze(boolean hiringFreeze)</code> method and the AgeBasedSalaryStrategy class has <code>setMinSalary(int minSalary)</code> and <code>setMaxSalary(int maxSalary)</code> methods.</para>
- <para>The values in the deployment descriptor are converted from strings into the relevant types (boolean, integer etc...) by JavaBean <ulink url="http://java.sun.com/j2se/1.5.0/docs/api/java/beans/PropertyEditor.html">PropertyEditors</ulink>. A large number of these are provided by default for standard types but you can easily create your own if necessary. See the Properties chapter in Part II 'POJO Development' for more details.</para>
- </section>
- <section>
- <title>Testing a service</title>
- <para>We should now have a good idea about how to create POJOs and configure them using an XML deployment descriptor so how do we go about testing them? Thankfully JBoss Microcontainer makes it extremely easy to unit test individual POJOs as well as POJOs that are wired together through the use of a MicrocontainerTest class.</para>
- <para>The org.jboss.test.kernel.junit.MicrocontainerTest class inherits from junit.framework.TestCase and as such it sets up each test by bootstrapping JBoss Microcontainer and adding a BasicXMLDeployer. It then looks on the classpath for an XML deployment descriptor with the same name as the test class (but ending in .xml) and residing in the same directory structure. Any beans found in this file are deployed and can then be accessed using a convenience method called <code>getBean(String name)</code>. </para>
- <para>You can see examples of these XML files in the src/test/resources directory:</para>
- <programlisting>org/jboss/example/service/HRManagerTestCase.xml
- /HRManagerAgeBasedTestCase.java
- /HRManagerLocationBasedTestCase.java
-
-org/jboss/example/service/util/AgeBasedSalaryTestCase.xml
- /LocationBasedSalaryTestCase.xml</programlisting>
- <para>Our java test source code is located in the src/test/java directory:</para>
- <programlisting>org/jboss/example/service/HRManagerTestCase.java
- /HRManagerAgeBasedTestCase.xml
- /HRManagerLocationBasedTestCase.xml
- /HRManagerTest.java
- /HRManagerTestSuite.java
-
-org/jboss/example/service/util/AgeBasedSalaryTestCase.java
- /LocationBasedSalaryTestVase.java
- /SalaryStrategyTestSuite.java</programlisting>
- <para>The HRManagerTest class extends MicrocontainerTest to set up a number of employees to use as the basis for the tests. Individual test cases then subclass this to perform the actual tests. You can also see a couple of TestSuite classes that are used to group individual test cases together for convenience.</para>
- <para>To run the tests simply enter <code>mvn test</code> from the <code>humanResourcesService/</code> directory. You should see some DEBUG log output which shows JBoss Microcontainer booting up and deploying the relevant XML file before running each test. At the end of the test it then undeploys the file and shuts down the microcontainer.</para>
- <note>
- <para>Some of the tests such as HRManagerTestCase, AgeBasedSalaryTestCase and LocationBasedSalaryTestCase simply unit test individual POJOs whilst other tests such as HRManagerAgeBasedTestCase and HRManagerLocationBasedTestCase unit test the whole service consisting of multiple POJOs wired together. Either way the method for conducting the tests remains the same. Thanks to the MicrocontainerTest class it is trivial to set up and conduct comprehensive tests for any part of your code.</para>
- <para>Finally note that we didn't unit test the Address or Employee classes here. They were deliberately left out as they contain only trivial logic which is very unlikely to break.</para>
- </note>
- </section>
- <section>
- <title>Packaging a service</title>
- <para>Now that we have successfully created and tested our service it is time to package it up so that others can use it. The simplest way to do this is to create a JAR containing all of the classes. You can choose to include the XML deployment descriptor if there is a sensible default way to configure the service but you are not required to.</para>
- <para>If you do choose to include the deployment descriptor then by convention you should call it <code>jboss-beans.xml</code> and put it in the META-INF directory. This helps if you want to later deploy the service in JBoss AS 5 as the default JAR deployer recognises this layout and will automatically deploy the service.</para>
- <para>In our case we will not include it as we want to easily configure the service in different ways by editing the descriptor directly. To generate a JAR in the <code>target</code> directory containing all of the compiled classes simply enter <code>mvn package</code> from the <code>humanResourcesService/</code> directory. </para>
- <para>To make the JAR available to other maven projects you then need to enter <code>mvn install</code> in order to copy it to your local maven repository.</para>
- <para>The final layout of the JAR is as follows:</para>
- <programlisting>org/jboss/example/service/Address.class
- /Employee.class
- /HRManager.class
-org/jboss/example/service/util/AgeBasedSalaryStrategy.class
- /LocationBasedSalaryStrategy.class
- /SalaryStrategy.class
-META-INF/MANIFEST.MF
-META-INF/maven/org.jboss.microcontainer.examples/humanResourcesService/pom.xml
- /pom.properties</programlisting>
- <para>The META-INF/maven directory is automatically produced by maven and is required so that other maven projects can use this JAR as a dependency. If you are not using maven as your build system then you will not have this directory.</para>
- </section>
- </chapter>
- <chapter>
- <title>Using services </title>
- <section>
- <title>Deploying a service</title>
- <para>Mention deploying a packaged service vs deploying an unpackaged service.</para>
- </section>
- <section>
- <title>Using the kernel controller</title>
- <para>This is equivalent to how you access beans using Spring.</para>
- </section>
- <section>
- <title>Using the kernel bus</title>
- <para>This provides the decoupling we need so that we can swap a service at runtime.</para>
- </section>
- <section>
- <title>Redeploying a service</title>
- <para>Show here how you can alter the jboss-beans.xml file in the unpackaged service and redeploy the service.</para>
- </section>
- <section>
- <title>Classloading</title>
- <para>Show how we can remove the ./deploy/humanResourcesService.jar from the classpath and then deploy the jboss-beans.xml file directly in the unpackaged service. We can then configure the <classloader> element of the deployment to point to the classes directory since they won't be available on the Application classpath anymore. We can even move the util package to another directory and show how we can set up a <classloader> element at the bean level.</para>
- </section>
- </chapter>
- <chapter>
- <title>Adding behaviour through AOP</title>
- <para/>
- <para/>
- <para/>
- </chapter>
- <chapter>
- <title>Advanced deployment</title>
- <section>
- <title>Aspectized Deployers </title>
- <para>Give example of using aspectized bean deployer and show how it's the same as the BasicXMLDeployer.</para>
- </section>
- <section>
- <title>Changing the package structure</title>
- <para>Give an example where we move the jboss-beans.xml file out of the META-INF directory and change the location of the classes.</para>
- </section>
- <section>
- <title>Changing the XML file format</title>
- <para>Give an example of changing the jboss-beans.xml file for a jboss-beans.properties file.</para>
- </section>
- <section>
- <title>Changing the classloading strategy</title>
- </section>
- <section>
- <title>Adding a deployment stage</title>
- </section>
- </chapter>
- </part>
- <part>
- <title>POJO Development</title>
- </part>
- <part>
- <title>AOP Development</title>
- </part>
- <part>
- <title>Extending the Microcontainer</title>
- <chapter>
- <title>Guice Extensions </title>
- </chapter>
- <chapter>
- <title>OSGi Extensions</title>
- </chapter>
- <chapter>
- <title>Drools Extensions</title>
- </chapter>
- <chapter>
- <title>jBPM Extensions</title>
- </chapter>
- </part>
- <part>
- <title>Integrating the Microcontainer</title>
- <chapter>
- <title>JBoss AS</title>
- <section>
- <title>Classloading</title>
- <para>Explain that the default classloading goes to the unified repository.</para>
- </section>
- <section>
- <title>Java EE Deployers</title>
- </section>
- <section>
- <title>MBean Compatibility</title>
- </section>
- <section>
- <title>Managing POJOs</title>
- </section>
- </chapter>
- </part>
- <appendix>
- <title>Additional Resources</title>
- <section>
- <title>Wiki</title>
- </section>
- <section>
- <title>Forums</title>
- </section>
- </appendix>
-</book>
Modified: projects/microcontainer/trunk/docs/User_Guide/pom.xml
===================================================================
--- projects/microcontainer/trunk/docs/User_Guide/pom.xml 2007-11-15 08:03:23 UTC (rev 67115)
+++ projects/microcontainer/trunk/docs/User_Guide/pom.xml 2007-11-15 08:55:33 UTC (rev 67116)
@@ -5,7 +5,7 @@
<modelVersion>4.0.0</modelVersion>
<groupId>org.jboss.microcontainer</groupId>
- <artifactId>microcontainer-user-guide-${translation}</artifactId>
+ <artifactId>user-guide-${translation}</artifactId>
<version>1.0-SNAPSHOT</version>
<packaging>jdocbook</packaging>
<name>User Guide (${translation})</name>
@@ -17,51 +17,49 @@
<artifactId>maven-jdocbook-plugin</artifactId>
<version>2.0.0</version>
<extensions>true</extensions>
- <!--dependencies>
- <dependency>
+ <dependencies>
+ <!--<dependency>
<groupId>org.hibernate</groupId>
<artifactId>hibernate-docbook-xslt</artifactId>
<type>jdocbook-style</type>
<version>0.1</version>
- </dependency>
- </dependencies-->
+ </dependency>-->
+ <!--<dependency>
+ <groupId>org.hibernate</groupId>
+ <artifactId>hibernate-jdocbook-style</artifactId>
+ <version>1.0.0</version>
+ <type>jdocbook-style</type>
+ </dependency>-->
+ </dependencies>
<configuration>
<sourceDocumentName>User_Guide.xml</sourceDocumentName>
<imageResource>
- <directory>en-US</directory>
- <excludes>
- <exclude>*.xml</exclude>
- </excludes>
+ <directory>src/main/images</directory>
</imageResource>
<cssResource>
- <directory>en-US</directory>
- <excludes>
- <exclude>*.xml</exclude>
- </excludes>
+ <directory>src/main/css</directory>
</cssResource>
<formats>
- <format>
+ <!--<format>
<formatName>pdf</formatName>
- <!--stylesheetResource>classpath:/standard/fopdf.xsl</stylesheetResource-->
+ <stylesheetResource>classpath:/xslt/standard/fopdf.xsl</stylesheetResource>
<finalName>User_Guide.pdf</finalName>
- </format>
+ </format>-->
<format>
<formatName>html</formatName>
- <!--stylesheetResource>classpath:/standard/html_chunk.xsl</stylesheetResource-->
+ <!--<stylesheetResource>classpath:/xslt/standard/html_chunk.xsl</stylesheetResource>-->
+ <stylesheetResource>file:${basedir}/src/main/xsl/main-html.xsl</stylesheetResource>
<finalName>index.html</finalName>
</format>
-<!--
- <format>
+ <!--<format>
<formatName>html_single</formatName>
<stylesheetResource>classpath:/xslt/nochunk-html.xsl</stylesheetResource>
- </format>
--->
-<!-- <format>
+ </format>-->
+ <!--<format>
<formatName>eclipse</formatName>
<stylesheetResource>classpath:/xslt/main-eclipse.xsl</stylesheetResource>
<finalName>index.html</finalName>
- </format>
--->
+ </format>-->
</formats>
<options>
<xincludeSupported>true</xincludeSupported>
@@ -70,8 +68,6 @@
<!-- could also locate the docbook dependency and inspect its version... -->
<docbookVersion>1.72.0</docbookVersion>
</options>
-
- <sourceDirectory>${basedir}/en-US</sourceDirectory>
</configuration>
</plugin>
</plugins>
@@ -79,6 +75,5 @@
<properties>
<translation>en-US</translation>
- </properties>
-
+ </properties>
</project>
Added: projects/microcontainer/trunk/docs/User_Guide/src/main/css/css/dirty.css
===================================================================
--- projects/microcontainer/trunk/docs/User_Guide/src/main/css/css/dirty.css (rev 0)
+++ projects/microcontainer/trunk/docs/User_Guide/src/main/css/css/dirty.css 2007-11-15 08:55:33 UTC (rev 67116)
@@ -0,0 +1,3 @@
+pre{-moz-border-radius:11px;}
+
+/*div.note,div.tip ,div.important ,div.caution ,div.warning{-moz-border-radius:11px;}*/
Added: projects/microcontainer/trunk/docs/User_Guide/src/main/css/css/docnav.css
===================================================================
--- projects/microcontainer/trunk/docs/User_Guide/src/main/css/css/docnav.css (rev 0)
+++ projects/microcontainer/trunk/docs/User_Guide/src/main/css/css/docnav.css 2007-11-15 08:55:33 UTC (rev 67116)
@@ -0,0 +1,22 @@
+/*document navigation*/
+.docnav a, .docnav strong{text-decoration:none;font-weight:normal;}
+.docnav{list-style:none;margin:0em;padding:0em;position:relative;width:100%;padding-bottom:2em;padding-top:1em;border-top:1px dotted #ccc;}
+.docnav li{list-style:none;margin:0em;padding:0em;display:inline;font-size:.8em;}
+.docnav li:before{content:" ";}
+.docnav li.previous, .docnav li.next{position:absolute;top:1em;}
+.docnav li.up, .docnav li.home{margin:0em 1.5em;}
+.docnav li.previous{left:0px;text-align:left;}
+.docnav li.next{right:0px;text-align:right;}
+.docnav li.previous strong, .docnav li.next strong{display:block;height:22px;}
+.docnav{margin:0 auto;text-align:center;}
+.docnav li.next a strong{background: url(../images/stock-go-forward.png) top right no-repeat;padding-top:3px;padding-right:28px;font-size:1.2em;}
+.docnav li.previous a strong{background: url(../images/stock-go-back.png) top left no-repeat;padding-top:3px;padding-left:28px;font-size:1.2em;}
+.docnav li.home a strong{background: url(../images/stock-home.png) top left no-repeat;padding:5px;padding-left:28px;font-size:1.2em;}
+.docnav li.up a strong{background: url(../images/stock-go-up.png) top left no-repeat;padding:5px;padding-left:28px;font-size:1.2em;}
+
+.docnav a:link, .docnav a:visited {color:#666 !important;}
+.docnav a:hover,.docnav a:focus, .docnav a:active{color:black !important;}
+.docnav a{max-width: 10em;overflow:hidden;}
+.docnav a:link strong{text-decoration:none;}
+
+.docnav{margin:0 auto;text-align:center;}
Added: projects/microcontainer/trunk/docs/User_Guide/src/main/css/css/documentation.css
===================================================================
--- projects/microcontainer/trunk/docs/User_Guide/src/main/css/css/documentation.css (rev 0)
+++ projects/microcontainer/trunk/docs/User_Guide/src/main/css/css/documentation.css 2007-11-15 08:55:33 UTC (rev 67116)
@@ -0,0 +1,208 @@
+
+
+
+/*Lists*/
+ol li ,ul li{padding-left:.2em;padding-bottom:.5em;margin:0em;}
+
+ul{padding-left:1.6em;list-style-image:url(../images/dot.png);list-style-type: circle;}
+ul ul{list-style-image:url(../images/dot2.png);list-style-type: circle;}
+dt {font-weight:bold;margin-bottom:0em;padding-bottom:0em;}
+dd{margin:0em;margin-left:2em;padding-top:0em;}
+li p:first-child, dd p:first-child{padding:0em;margin-top:.3em;}
+.variablelist,.itemizedlist{margin-top:.6em;}
+ul li p:first-child{margin:0em;}
+/*images*/
+img{display:block;margin:2em 0;}
+.inlinemediaobject,.inlinemediaobject img{display:inline !important;margin:0em;}
+
+/*document modes*/
+.confidential{background-color:#900; color:White; padding:.5em .5em; font-family:serif; text-transform:uppercase; text-align:center}
+
+dt a{font-weight: normal;}
+.longdesc-link{display:none;}
+.prompt{background-color:#ede7c8;padding:0em .3em;}
+
+/*user interface styles*/
+.screen .replaceable {color:#444;}
+.screen{background-color:#ede7c8;color:#333;padding:.5em 1em;margin:0em;}
+pre,code,.guibutton,.keycap,.guilabel{font-size:0.9em;font-family:"liberation mono", "Bitstream vera mono",monospace;}
+.guibutton,.keycap,.guilabel{font-weight:bold;white-space:nowrap;color:#444;font-family:"liberation sans", "Bitstream vera sans", "dejavu sans" sans-serif;}
+.guibutton,.guilabel{}
+.keycap{padding: .1em .4em;}
+.example {background-color:#c8c5ac; padding:5px; margin-bottom:10px;}
+
+
+/*terminal/console text*/
+.command,
+.computeroutput,
+.filename,
+.citetitle,
+.replaceable,
+.option{font-weight:bold;}
+.command .replaceable{color:#555;}
+pre{display:block;background-color:#f7f2d0;color:#333;overflow:auto;}
+code{white-space:nowrap;}
+
+/*Notifications*/
+div.note,div.tip ,div.important ,div.caution ,div.warning{
+ background: #555753; color:white;padding:1em;padding-bottom:20px;border:1px solid #444;margin-bottom:1.5em;background-repeat:no-repeat; background-position:10px 10px;
+}
+
+div.note pre,div.tip pre ,div.important pre ,div.caution pre ,div.warning pre{background-color:#333; color:white;}
+div.note,div.tip ,div.important ,div.caution ,div.warning{margin-top:.5em;}
+div.note{background-image:url(../images/note.png)}
+div.tip{background-image:url(../images/tip.png)}
+div.important{background-image:url(../images/important.png)}
+div.caution{background-image:url(../images/caution.png)}
+div.warning{background-image:url(../images/warning.png)}
+div.note .replaceable,div.tip .replaceable,div.important .replaceable,div.caution .replaceable,div.warning .replaceable{
+ color:#e3dcc0;
+ }
+
+pre .replaceable, tt .replaceable{
+ color:#444 !important;
+ }
+div.note h2,div.tip h2,div.important h2,div.caution h2,div.warning h2{height:32px;font-size:1.3em;color:white;}
+
+div.note .guilabel,div.tip .guilabel,div.important .guilabel,div.caution .guilabel,div.warning .guilabel{color:white !important;}
+/*
+div.note h2,div.tip h2,div.important h2,div.caution h2,div.warning h2{
+ background-color:transparent;background-position:top left;background-repeat:no-repeat;height:48px;font-size:1.3em;color:#ede7c8;
+ }
+ */
+
+div.note li,div.tip li,div.caution li,div.warning li,div.important li{
+ padding-left:10px;margin:0em;
+ }
+
+div.note ul,div.tip ul,div.caution ul,div.warning ul,div.important ul{
+ padding-left:40px;margin:0em;
+ }
+
+div.note pre pre a:visited,div.tip pre pre a:visited,div.important pre pre a:visited,
+div.caution pre pre a:visited,div.warning pre pre a:visited,div.note pre a:link,
+.tip pre a:link,div.important pre a:link,div.caution pre a:link,div.warning pre a:link{
+ color:#0066cc !important;
+ }
+
+div.note a:visited,div.tip a:visited ,div.important a:visited ,div.caution a:visited ,
+div.warning a:visited,div.note a:link ,div.tip a:link ,div.important a:link ,div.caution a:link ,div.warning a:link{
+ color:#f7f2d0;
+ }
+
+/*notification icons*/
+div.note h2,div.note p,div.tip h2,div.tip p,div.caution h2,div.caution p,div.warning h2,div.warning p,div.important h2,.important p {padding:0em;margin:0em;padding-left:56px;}
+/*div.note h2{background-image:url(../images/note.png)}
+div.tip h2{background-image:url(../images/tip.png)}
+div.caution h2{background-image:url(../images/caution.png)}
+div.warning h2{background-image:url(../images/warning.png)}
+div.important h2{background-image:url(../images/important.png)}
+*/
+/*Page Title*/
+#title strong{display:none;}
+#title a{display:block;height:45px;width:110px;padding-left:200px;background:transparent url(../images/rhlogo.png) top left no-repeat;}
+#title{display:block;height:45px;background:transparent url(../images/documentation.png) top right no-repeat;padding-bottom:1em;}
+
+/*Table*/
+table{border:1px solid #aaa;width:100%;border-collapse:collapse;}
+table th{text-align:left;background-color:#900;padding:.3em .5em;color:white;}
+table td{padding:.15em .5em;}
+table tr.even td{background-color:#f5f5f5;}
+table th p:first-child,table td p:first-child,table li p:first-child{margin-top:0em;padding-top:0em;display:inline;}
+
+th, td{border-style:none;;}
+table table td{border-bottom:1px dotted #aaa !important;background-color:white;padding:.6em 0em;}
+table table{border:1px solid white !important;font-size:.9em;}
+
+
+td.remarkval{font-size:.9em;color:#444;}
+.defaultval{font-size:.8em}
+td.typeval{font-size:.8em}
+
+td.fieldval{font-weight:bold; font-size:.9em;}
+
+th.dbkey{font-size:.9em;}
+
+.lbname,.lbtype,.lbdescr,.lbdriver,.lbhost{color:white;font-weight:bold;background-color:#999;font-size:0.9em;width:120px;}
+td.remarkval{width:230px;}
+
+td.tname{font-weight:bold;font-size:1.1em;}
+h5{font-size:9pt;}
+h6{font-size:10pt;}
+th.dbfield{width:120px;}
+th.dbtype{width:70px;}
+th.dbdefault{width:70px;}
+th.dbnul{width:70px;}
+th.dbkey{width:70px;}
+
+span.book{margin-top:4em;display:block;}
+span.chapter{display:block;margin-top:0.5em;}
+
+/*Breadcrumbs*/
+#breadcrumbs ul li.first:before{content:" ";}
+#breadcrumbs{color:#900;padding:3px;margin-bottom:25px;}
+#breadcrumbs ul{margin-left:0;padding-left:0;display:inline;border:none;}
+#breadcrumbs ul li{margin-left:0;padding-left:2px;border:none;list-style:none;display:inline;}
+#breadcrumbs ul li:before{content:"\0020 \0020 \0020 \00BB \0020";color:#333;}
+
+/*status*/
+.alpha1{background: white url(../images/watermark-alpha1.png) top left repeat;}
+.alpha2{background: white url(../images/watermark-alpha2.png) top left repeat;}
+.beta1{background: white url(../images/watermark-beta1.png) top left repeat;}
+.beta2{background: white url(../images/watermark-beta2.png) top left repeat;}
+.pre-release-candidate{background: white url(../images/watermark-pre-release-candidate.png) top left repeat;}
+.release-candidate{background: white url(../images/watermark-release-candidate.png) top left repeat;}
+
+/*index*/
+.glossary h3,
+.index h3{font-size: 2em;color:#aaa;margin:0em;}
+.indexdiv{margin-bottom:1em;}
+.glossary dt,.index dt{font-size:.9em;color:#444;padding-top:.5em;}
+.glossary dl dl dt,
+.index dl dl dt{font-size:.85em;color:#777;line-height:1.2em;font-weight:normal;padding-top:0em;}
+.index dl dl dt:before{content:"- ";color:#ccc;}
+
+/*changes*/
+.footnotes{}
+.footnote {padding:.2em 1em;background-color:#c8c5ac;font-size: .9em;margin:0em;margin-bottom:.5em;color:#222;}
+table .footnote{margin:1em .5em;}
+sup{padding:0em .3em;padding-left:0em;}
+.footnote{position:relative;}
+.footnote sup {color:#e3dcc0;font-size:1.8em;position:absolute;left: .4em;}
+.footnote sup a:link,
+.footnote sup a:visited{color:#92917d;text-decoration:none;}
+.footnote:hover sup a{color:#fff;text-decoration:none;}
+.footnote p{padding-left:5em;}
+.footnote a:link,
+.footnote a:visited{color:#00537c;}
+.footnote a:hover{color:white;}
+
+li p:first-child{margin:0em !important; padding:0em !important;}
+
+/**/
+div.chapter, div.section {padding-top:2em;}
+
+.revhistory{font-size:}
+
+pre .replaceable,
+pre .keycap{color:white;}
+pre{font-family:"liberation mono", "bitstream vera mono", "dejavu mono" monospace;}
+
+div.note .replaceable,
+div.tip .replaceable,
+div.important .replaceable,
+div.caution .replaceable,
+div.warning .replaceable,
+div.note .keycap,
+div.tip .keycap,
+div.important .keycap,
+div.caution .keycap,
+div.warning .keycap,
+{color:white;}
+div.abstract{font-size:larger;}
+
+.authorgroup {}
+.authorgroup h4{padding:0em; margin:0em;margin-top:1em;}
+.author, .editor, .translator, .othercredit{display:block;}
+
+ul li p:last-child{margin-bottom:0em; padding-bottom:0em;}
Added: projects/microcontainer/trunk/docs/User_Guide/src/main/css/css/reports.css
===================================================================
--- projects/microcontainer/trunk/docs/User_Guide/src/main/css/css/reports.css (rev 0)
+++ projects/microcontainer/trunk/docs/User_Guide/src/main/css/css/reports.css 2007-11-15 08:55:33 UTC (rev 67116)
@@ -0,0 +1,55 @@
+
+/* Reports */
+.reports ul.locale{list-style:none;}
+.reports ul{padding:0em;margin:0em;}
+.reports ul.locale li{font-size:small;color:#000;display:block;border:1px solid #eee;float:left;padding-right:2em;margin-right:1em;margin-bottom:1em;}
+.reports ul.locale li a{font-size:1.2em;display:block;padding-top:.1em;padding-bottom:.5em;}
+.reports ul.locale strong{display:block;margin:0em;padding:0em;margin-bottom:-2.2em;}
+.reports ul.locale span.value{display:block;position:relative;text-align:right;margin-right:-1.5em;font-size:1.0em;color:#444;}
+.reports ul.locale li{width:12em;display:block;float:left;margin:0em;clear:none;}
+.reports ul.locale li div.progress{font-size:1em;width:13.2em;position:relative; left: 0em; top:0em; margin-bottom:0em;}
+.reports h2{font-size:1em;margin:0em;}
+.reports li{}
+.reports li:hover{background-color:#666;border-color:#444 !important;color:white !important;}
+.reports li:hover strong, .reports li:hover h2, .reports li:hover a, .reports li:hover span.value{color:white;}
+
+/*uniform*/
+body.results, body.reports{max-width:57em !important;padding:0em !important}
+/*Progress Bar*/
+div.progress{display:block;float:left;width:16em;background:#c00 url(../images/shine.png) top left repeat-x;height:1em;}
+div.progress span{height:1em; float:left;}
+div.progress span.translated{background:#6c3 url(../images/shine.png) top left repeat-x;}
+div.progress span.fuzzy{background:#ff9f00 url(../images/shine.png) top left repeat-x;}
+
+
+
+
+/*Results*/
+
+.results ul.locale{list-style:none;padding:0em;margin:0em;}
+.results .pofile{padding:0em !important;margin:0em;}
+.results ul.locale li{border-top:1px solid #eee;padding:0em; margin:0em;padding-left:32px;}
+.results ul.locale .pofile{font-size:1.2em;display:block;width:100%;color:#444;padding:0em;margin:0em;}
+.results span.value{color:#888;}
+.results strong{font-weight: normal;}
+.results .home a{display:block;margin:0 auto;width:5em;background: url(../images/stock-home.png) top left no-repeat;padding:5px;padding-left:28px;font-size:1.2em;}
+.results ul.locale li:hover, .results ul.locale li:hover span.pofile ,.results ul.locale li:hover strong, .results ul.locale li:hover span.value{background-color:#666 !important;color:white;}
+
+ul.locale{list-style:none;}
+ul.locale li.total{font-size:small;color:#777;width:31em;display:block;float:left;margin-right:2em;clear:none !important;}
+ul.locale li{clear:both;font-size:small;color:#777;display:block;}
+ul.locale strong, span.value {font-weight:normal;color:#888;font-size:.7em;}
+ul.locale li a{font-size:1.2em;display:block;padding-top:.2em;}
+ul.locale li.total div.progress{position:relative;left:0em;top:0em;margin-bottom:0em; }
+ul.locale li{width:100%;}
+ul.locale li div.progress{float:left;position:relative; left:30.5em; top:-2em; margin:0em;margin-bottom:-3em;}
+
+li.total{padding:0em !important;}
+li.total{float:right;max-width:16em;padding:.5em;margin:0 auto;padding-top: .5em;background-color:#f7f2d0;font-size: 1.3em !important;color:#ccc !important;margin-bottom:1em;min-height:9.5em;}
+li.total .value{color:#444;font-size:.8em;}
+li.total strong{display:block;color:black;font-weight:bold;}
+li.total span.value {position:relative;display:block;top:-1.25em;text-align:right;}
+
+
+.pofile{position:relative;}
+
Added: projects/microcontainer/trunk/docs/User_Guide/src/main/css/css/rhel.css
===================================================================
--- projects/microcontainer/trunk/docs/User_Guide/src/main/css/css/rhel.css (rev 0)
+++ projects/microcontainer/trunk/docs/User_Guide/src/main/css/css/rhel.css 2007-11-15 08:55:33 UTC (rev 67116)
@@ -0,0 +1,61 @@
+ at import url("documentation.css");
+ at import url("docnav.css");
+ at import url("reports.css");
+
+ at import url("dirty.css");
+
+body{
+ background-color: white;
+ margin:0 auto;
+ font-family: "liberation sans", "Myriad ", "Bitstream Vera Sans","Lucida Grande", verdana, "Luxi Sans","Trebuchet MS", helvetica,verdana,arial,sans-serif;
+ font-size:12px;
+ max-width:55em;
+ padding:0em 2em;
+ color:#333;
+ line-height:150%;
+ }
+
+/*Links*/
+a:link{color:#0066cc;}
+a:visited{color:#6699cc;}
+div.longdesc-link{float:right;color:#999;}
+
+
+/*headings*/
+h1,h2,h3,h4,h5,h6{color:#a70000;
+ line-height:130%;
+ margin-top:0em;
+ font-family:"liberation sans","Bitstream Vera Sans","Lucida Grande","Trebuchet MS",helvetica,verdana,arial,sans-serif;
+ background-color:transparent;
+ }
+
+h1{background: #800 url(../images/red-bg.png) top left repeat;
+ line-height:1.2em;
+ color:white;
+ font-size:2em;
+ padding:1.5em;
+ }
+
+h2{font-size:1.6em;
+ }
+
+h3{font-size:1.3em;
+ padding-top:0em;
+ padding-bottom:0em;
+ }
+h4{font-size:1.1em;
+ padding-top:0em;
+ padding-bottom:0em;
+ }
+
+h5.formalpara {font-size:1em;
+ margin-top:2em;margin-bottom:.8em;
+ }
+
+
+/*element rules*/
+hr{border-collapse: collapse;border-style:none;border-top: 1px dotted #ccc;width:100% !important;}
+sup{color:#999;}
+
+/*supporting stylesheets*/
+
Copied: projects/microcontainer/trunk/docs/User_Guide/src/main/docbook/Author_Group.xml (from rev 67085, projects/microcontainer/trunk/docs/User_Guide/en-US/Author_Group.xml)
===================================================================
--- projects/microcontainer/trunk/docs/User_Guide/src/main/docbook/Author_Group.xml (rev 0)
+++ projects/microcontainer/trunk/docs/User_Guide/src/main/docbook/Author_Group.xml 2007-11-15 08:55:33 UTC (rev 67116)
@@ -0,0 +1,7 @@
+<?xml version='1.0' encoding='UTF-8'?>
+<!DOCTYPE authorgroup PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
+]>
+<authorgroup>
+ <corpauthor>Mark Newton</corpauthor>
+ <corpauthor>Aleš Justin</corpauthor>
+</authorgroup>
Copied: projects/microcontainer/trunk/docs/User_Guide/src/main/docbook/Legal_Notice.xml (from rev 67085, projects/microcontainer/trunk/docs/User_Guide/en-US/Legal_Notice.xml)
===================================================================
--- projects/microcontainer/trunk/docs/User_Guide/src/main/docbook/Legal_Notice.xml (rev 0)
+++ projects/microcontainer/trunk/docs/User_Guide/src/main/docbook/Legal_Notice.xml 2007-11-15 08:55:33 UTC (rev 67116)
@@ -0,0 +1,17 @@
+<?xml version='1.0'?>
+<!DOCTYPE legalnotice PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
+]>
+
+<legalnotice id="Book-Legal_Notice">
+ <title>Legal Notice</title>
+ <para>
+ <address>
+ <street>1801 Varsity Drive</street>
+ <city>Raleigh</city>, <state>NC</state><postcode>27606-2072</postcode><country>USA</country><phone>Phone: +1 919 754 3700</phone>
+ <phone>Phone: 888 733 4281</phone>
+ <fax>Fax: +1 919 754 3701</fax>
+ <pob>PO Box 13588</pob><city>Research Triangle Park</city>, <state>NC</state><postcode>27709</postcode><country>USA</country>
+ </address>
+ </para>
+</legalnotice>
+
Copied: projects/microcontainer/trunk/docs/User_Guide/src/main/docbook/User_Guide.xml (from rev 67085, projects/microcontainer/trunk/docs/User_Guide/en-US/User_Guide.xml)
===================================================================
--- projects/microcontainer/trunk/docs/User_Guide/src/main/docbook/User_Guide.xml (rev 0)
+++ projects/microcontainer/trunk/docs/User_Guide/src/main/docbook/User_Guide.xml 2007-11-15 08:55:33 UTC (rev 67116)
@@ -0,0 +1,421 @@
+<?xml version='1.0' encoding='UTF-8'?>
+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN" "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd" [
+<!ENTITY % RH-ENTITIES SYSTEM "Common_Config/rh-entities.ent">
+]>
+<book>
+ <bookinfo>
+ <title>JBoss Microcontainer 2.0.0</title>
+ <subtitle>User Guide</subtitle>
+ <issuenum>2.0</issuenum>
+ <productnumber>2</productnumber>
+ <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Author_Group.xml"/>
+ <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Legal_Notice.xml"/>
+ </bookinfo>
+ <preface>
+ <title>What this Book Covers</title>
+ <para>This book aims to help you become familiar with JBoss Microcontainer in order that you can use it to develop your own services or applications.</para>
+ <para>Part I 'Getting Started' introduces the technology and explains how it relates to Java development in general. It then goes on to cover a complete use-case so that you can quickly see how the microcontainer works in real-life.</para>
+ <para>Part II 'POJO Development' takes a look at the various methods you can use to construct POJOs and wire them together using injections together with other features.</para>
+ <para>Part III 'AOP Development' goes on to look at how you can add behaviour to your POJOs using Aspects and covers the various ways this can be done.</para>
+ <para> Part IV 'Extending the Microcontainer' shows how you can write your own extensions by creating new dependencies and gives some examples of how this has already been done.</para>
+ <para>Part V 'Integrating the Microcontainer' covers how the microcontainer is used in JBoss AS 5 as the integration technology for the various services and core infrastructure. We also look at how legacy services, developed using MBeans, remain compatible with the new microcontainer and see how it is possible to manage POJO services at runtime.</para>
+ </preface>
+ <part>
+ <title>Getting Started</title>
+ <chapter id="overview">
+ <title>Introduction</title>
+ <para>The Java platform has traditionally been distributed in 3 editions, each providing a different type of runtime environment: </para>
+ <itemizedlist>
+ <listitem>
+ <para>Java ME (Micro Edition) - Mobile or other embedded devices</para>
+ </listitem>
+ <listitem>
+ <para>Java SE (Standard Edition) - Desktop machines or servers (typically running 2-tier applications)</para>
+ </listitem>
+ <listitem>
+ <para>Java EE (Enterprise Edition) - Servers (typically running 3-tier applications)</para>
+ </listitem>
+ </itemizedlist>
+ <para>Each environment aims to provide a base level of functionality on top of which developers can add their own code to create applications. For example Java SE provides networking and security libraries together with graphical user interface toolkits to facilitate the development of desktop and simple client-server applications. Java EE takes this a stage further by adding a number of 'enterprise' services such as transactions, messaging, and persistence that allow much more robust and scalable 'enterprise' applications to be developed. These services are typically combined together inside a JEE application server to provide a standard runtime environment for enterprise applications but there are often occasions when some services are never used.</para>
+ <para>Having unused services in your environment is undesirable as they can take up valuable resources such as CPU and memory. They can also clutter up the environment with unnecessary configuration files, complicating maintenance and adding unnecessary complexity. It would be better if there was a controlled way to remove such services without breaking any dependencies they might have. Similarly there are often occasions when applications need services that aren't provided by JEE so it would be better if there was a controlled way to add them, again making sure that any dependencies were first satisfied.</para>
+ <para>JBoss Microcontainer aims to provide these capabilities by allowing services, created using Plain Old Java Objects (POJOs), to be deployed into a standard Java SE runtime environment in a controlled manner to create a customized environment for your applications. Dependencies between services are fully managed by the microcontainer to ensure that new services cannot be deployed until services they depend on have first been deployed. Likewise undeploying a service causes all dependent services to first be undeployed in order to maintain the integrity of the system. </para>
+ <para>Deploying services in this way, on top of a Java SE environment, is exactly how we have created the latest version of JBoss Application Server (JBoss AS 5.0) which provides a standard Java EE environment. If you need additional services then you can simply deploy these on top of Java EE to provide the functionality you need. This even applies when using the microcontainer in different Java EE environments such as Glassfish since you can plug in different classloading models during the service deployment phase.</para>
+ <para>Since JBoss Microcontainer is very lightweight and deals with POJOs it can also be used to deploy services into a Java ME runtime environment. This opens us new possibilities for mobile applications that can now take advantage of enterprise services without requiring a full JEE application server. </para>
+ <para>In common with other lightweight containers JBoss Microcontainer uses dependency injection to wire individual POJOs together to create services. Configuration is performed using either XML or annotations depending on where the information is best located. Finally unit testing is made extremely simple thanks to a helper class that extends JUnit to setup the test environment, allowing you to access POJOs and services from your test methods using just a few lines of code.</para>
+ </chapter>
+ <chapter>
+ <title>Download and Installing</title>
+ <para>JBoss Microcontainer 2.0.0 is currently only available as a beta release via Maven2. This means that you need to install and configure Maven before you can begin development. Once this is done then you can create a maven project that depends on the JBoss Microcontainer JARs in order to download and install them into your local maven repository. You can then create an assembly for your final application in order to package the relevant JARs into a distributable format.</para>
+ <para>The examples created for this User Guide use Maven2 to achieve exactly this so it is highly recommended that you <ulink url="http://labs.jboss.com/file-access/default/members/jbossmc/downloads/userGuide-examples-13112007.zip">download</ulink> these first and take a look at how they work.</para>
+ <note>
+ <para>To build and run the examples you first need to install and configure Maven 2.0.7 available from <ulink url="http://maven.apache.org/">http://maven.apache.org/</ulink></para>
+ </note>
+ <para>Installation is performed by downloading and unzipping the maven-2.0.7-bin.zip file to a convenient location on your local disk. Configuration consists of adding $MAVEN_HOME/bin to your path and adding the following profile to your ~/.m2/settings.xml file:</para>
+ <para><programlisting><settings>
+ <profiles>
+ <profile>
+ <id>jboss.repository</id>
+ <activation>
+ <property>
+ <name>!jboss.repository.off</name>
+ </property>
+ </activation>
+ <repositories>
+ <repository>
+ <id>snapshots.jboss.org</id>
+ <url>http://snapshots.jboss.org/maven2</url>
+ <snapshots>
+ <enabled>true</enabled>
+ </snapshots>
+ </repository>
+ <repository>
+ <id>repository.jboss.org</id>
+ <url>http://repository.jboss.org/maven2</url>
+ <snapshots>
+ <enabled>false</enabled>
+ </snapshots>
+ </repository>
+ </repositories>
+ <pluginRepositories>
+ <pluginRepository>
+ <id>repository.jboss.org</id>
+ <url>http://repository.jboss.org/maven2</url>
+ <snapshots>
+ <enabled>false</enabled>
+ </snapshots>
+ </pluginRepository>
+ <pluginRepository>
+ <id>snapshots.jboss.org</id>
+ <url>http://snapshots.jboss.org/maven2</url>
+ <snapshots>
+ <enabled>true</enabled>
+ </snapshots>
+ </pluginRepository>
+ </pluginRepositories>
+ </profile>
+ </profiles>
+</settings></programlisting></para>
+ <para>This profile informs maven of the two JBoss repositories (snapshots and releases) that are needed to download the JBoss Microcontainer and dependant JARs.</para>
+ <para>Once you have configured Maven and downloaded the examples then you can go to one of the following directories in the <code>examples/User_Guide</code> directory and enter <code>mvn install</code> to perform a build:</para>
+ <para/>
+ <itemizedlist>
+ <listitem>
+ <para>gettingStarted - projects for creating and using a service together with AOP</para>
+ </listitem>
+ <listitem>
+ <para>pojoDevelopment - examples of creating and configuring POJOs using XML and Annotations</para>
+ </listitem>
+ <listitem>
+ <para>aopDevelopment - examples of using AOP to add behaviour to POJOs</para>
+ </listitem>
+ <listitem>
+ <para>extending - examples of how we have created various extensions to the core microcontainer by creating new dependencies</para>
+ </listitem>
+ <listitem>
+ <para>integrating - examples of how the microcontainer forms the basis of JBoss AS 5 and how you can deploy MBean services alongside POJO services for backwards compatibility</para>
+ </listitem>
+ </itemizedlist>
+ <para>Instructions on how to run the individual examples can be found in the relevant parts of this guide.</para>
+ </chapter>
+ <chapter>
+ <title>Building services</title>
+ <para><emphasis role="bold">
+ <emphasis role="underline">POJOs</emphasis>
+ </emphasis></para>
+ <para>The term POJO is an acronym for Plain Old Java Object and was first coined while Rebecca Parsons, Josh MacKenzie, and Martin Fowler were preparing for a talk at a conference in September 2000. It describes the practice of encoding business logic in regular java objects instead of components such as EJB 2.1 Entity Beans. The benefit of this approach is that you're not required to implement any special interfaces. This not only keeps your code simple but allows it to be used in a wider variety of environments and makes it easy to unit test.</para>
+ <para><emphasis role="bold">Definition:</emphasis> <emphasis role="italic">A POJO declares business methods, which define behaviour, and properties, which represent state. Some properties represent associations to other POJOs.</emphasis></para>
+ <para>For experienced developers this should sound familiar as it mimicks almost exactly the proposals set out in the JavaBeans specification. JavaBeans describes a component model for User Interface development emphasizing simplicity and standardized naming conventions for property accessor methods. The idea was that this would allow automatic discovery of an object's properties so that an instance could easily be created and populated with state at runtime. The main use case was creating and configuring visual user interface components such as text boxes, buttons, and tables from within an integrated development environment (IDE).</para>
+ <para><emphasis role="bold">Definition:</emphasis> <emphasis role="italic">A Java Bean is a reusable software component that can be manipulated visually in a builder tool.</emphasis></para>
+ <para> Importantly a Java Bean is not required to inherit from any particular base class or interface. Also while Java Beans are primarily targeted at builder tools they are entirely usable by human programmers with conventional text editors.</para>
+ <para>Strictly speaking a Java Bean should include support for events and persistence but in many cases developers choose not to implement these features and simply follow the standardized naming conventions for property accessor methods; i.e. get and set. This 'lightweight' form of Java Bean is commonly referred to as simply a 'bean' and is semantically equivalent to a POJO.</para>
+ <para>The terms POJO and bean are therefore interchangeable and you will encounter both in the microcontainer documentation and configuration files.</para>
+ <para><emphasis role="bold">
+ <emphasis role="underline">Services</emphasis>
+ </emphasis></para>
+ <para>The word 'service' has many definitions in the English language but in the context of developing Java applications it is helpful to define it as follows:</para>
+ <orderedlist>
+ <listitem>
+ <para>A service should perform work that is useful to multiple clients, thereby preventing each client from having to perform the work themselves.</para>
+ </listitem>
+ <listitem>
+ <para>A service should have a name that clients can lookup at runtime to gain access. This provides a standard way to access different kinds of services and removes the need for clients to explicitly create services before they can be used. </para>
+ </listitem>
+ <listitem>
+ <para>Internal changes to a service should not affect any clients. In practice this means that clients should access a service using a well defined interface so that the service implementation can be changed without having to recompile any clients. </para>
+ </listitem>
+ </orderedlist>
+ <para>Using this definition we can now answer some simple questions:</para>
+ <para>Q) Is a POJO a service?</para>
+ <para>A) No, because although it performs work that is useful to multiple clients you cannot access it using a name. Clients have to create a POJO themselves either directly using the <code>new</code> operator or indirectly using a factory. </para>
+ <para>Q) Does a class have to implement an interface in order to provide a 'well-defined' interface?</para>
+ <para>A) Not necessarily. Providing that we don't remove fields or methods from a class, or restrict access to them, then we can always change its implementation without needing to recompile the client. See the section entitled <ulink url="http://java.sun.com/docs/books/jls/second_edition/html/execution.doc.html#44524">Resolution of Symbolic References</ulink> from the Java Language Specification for more details:</para>
+ <para>The 'well-defined' interface in this respect is composed from the original class's fields and method signatures together with their access modifiers.</para>
+ <note>
+ <para>Implementing an interface is only necessary if we want to allow a client to <emphasis role="bold">choose</emphasis> between <emphasis role="bold">alternative implementations</emphasis>. i.e. if the client is compiled against an interface then we can provide as many different implementations of the interface as we like without having to recompile the client.</para>
+ </note>
+ <para>What then must we do in order to create a service using a POJO? The answer is to provide a naming mechanism that allows us to register a reference to the POJO instance with a name. Clients can then lookup the POJO reference using the name at runtime and use it to perform work. The POJO class is not required to implement an interface unless it is important that the client can choose between alternative implementations. </para>
+ <para>JBoss Microcontainer provides such a naming mechanism in order that we can deploy our POJO services into a runtime environment such as Java SE and look them up from within our applications.</para>
+ <para>Since robust implementations of Java EE services are already available from JBoss.org and other communities, it is common for companies to focus on creating more 'business-oriented' services. For this reason we shall look at creating, configuring and testing a simple Human Resources service that could potentially be used in a wide-variety of companies.</para>
+ <section>
+ <title>Creating POJOs</title>
+ <para>The example that relates to this section can be found in the <code>examples/User_Guide/gettingStarted/humanResourcesService</code> directory. The directory layout, as with all of the examples for this User Guide, follows the <ulink url="http://maven.apache.org/guides/introduction/introduction-to-the-standard-directory-layout.html">Maven Standard Directory Layout</ulink>.</para>
+ <para><programlisting>humanResourcesService/pom.xml
+ /src/main/java
+ /test/java
+ /test/resources</programlisting></para>
+ <para>Java source files are located in packages beneath the src/main/java directory:</para>
+ <para><programlisting>org/jboss/example/service/Address.java
+ /Employee.java
+ /HRManager.java
+
+org/jboss/example/service/util/SalaryStrategy.java
+ /AgeBasedSalaryStrategy.java
+ /LocationBasedSalaryStrategy.java</programlisting></para>
+ <para>As you can see from looking at the source code, each of these classes represents a simple POJO that doesn't implement any special interfaces. The most important class is HRManager as this represents the service entry point and therefore provides all of the public methods that clients will call.</para>
+ <para/>
+ <itemizedlist>
+ <listitem>
+ <para>addEmployee(Employee employee)</para>
+ </listitem>
+ <listitem>
+ <para>getEmployees()</para>
+ </listitem>
+ <listitem>
+ <para>getEmployee(String firstName, String lastName)</para>
+ </listitem>
+ <listitem>
+ <para>removeEmployee(Employee employee)</para>
+ </listitem>
+ <listitem>
+ <para>getSalary(Employee employee)</para>
+ </listitem>
+ <listitem>
+ <para>setSalary(Employee employee, Integer newSalary)</para>
+ </listitem>
+ <listitem>
+ <para>isHiringFreeze()</para>
+ </listitem>
+ <listitem>
+ <para>setHiringFreeze(boolean hiringFreeze)</para>
+ </listitem>
+ <listitem>
+ <para>getSalaryStrategy()</para>
+ </listitem>
+ <listitem>
+ <para>setSalaryStrategy(SalaryStrategy strategy)</para>
+ </listitem>
+ </itemizedlist>
+ <para>The Human Resources Service is therefore composed of the above 6 classes which work together to allow a list of employees, together with details of their addresses and salaries, to be maintained by an HRManger. In addition it is possible to configure HRManager so that different salary strategies are used. These place minimum and maximum limits on the salaries that can be awarded to employees depending on various rules.</para>
+ <para>To compile the source code you simply need to enter <code>mvn compile</code> from the <code>humanResourcesService/</code> directory. This will create a new directory called <code>target/classes</code> containing the compiled code. To clean up the humanResourcesService project and remove the <code>target</code> directory simply enter <code>mvn clean</code>. </para>
+ <para>Now that we have compiled our POJO classes we need to determine how to create instances of them. This is done by creating an XML deployment descriptor that contains a list of beans representing individual instances. Each bean is given a name so that the instance can be looked up at runtime by clients.</para>
+ <programlisting><?xml version="1.0" encoding="UTF-8"?>
+
+<deployment xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ xsi:schemaLocation="urn:jboss:bean-deployer:2.0 bean-deployer_2_0.xsd"
+ xmlns="urn:jboss:bean-deployer:2.0">
+
+ <bean name="HRService" class="org.jboss.example.service.HRManager"/>
+
+</deployment></programlisting>
+ <para>Here we have declared that we want to create an instance of the HRManager class and register it with the name HRService. This file is passed to a deployer associated with the microcontainer at runtime which performs the actual deployment and instantiates the beans.</para>
+ </section>
+ <section>
+ <title>Wiring POJOs together </title>
+ <para>So far we have seen how to create POJOs and declare instances of them together with names in the XML deployment descriptor. However, individual POJO instances can only provide relatively simple behaviour. Things really get interesting when we combine POJOs together to perform more complex tasks. In our example we know that we can choose a number of different salary strategies for the HRManager so how do we go about wiring the POJOs together?</para>
+ <para>The answer is to use the XML deployment descriptor again as follows:</para>
+ <programlisting><?xml version="1.0" encoding="UTF-8"?>
+
+<deployment xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ xsi:schemaLocation="urn:jboss:bean-deployer:2.0 bean-deployer_2_0.xsd"
+ xmlns="urn:jboss:bean-deployer:2.0">
+
+ <bean name="HRService" class="org.jboss.example.service.HRManager">
+ <property name="salaryStrategy"><inject bean="AgeBasedSalary"/></property>
+ </bean>
+
+ <bean name="AgeBasedSalary"
+ class="org.jboss.example.service.util.AgeBasedSalaryStrategy"/>
+
+</deployment></programlisting>
+ <para>We first need to create an instance of our chosen salary strategy by including an additional <bean> element. Here we have chosen the AgeBasedSalaryStrategy. Next we need to inject a reference to this bean into the instance of HRManager created using the HRService bean. Injection is possible as the HRManager class contains a <code>setSalaryStrategy(SalaryStrategy strategy)</code> method. Behind the scenes JBoss Microcontainer will call this method on the newly created HRManager instance and pass in a reference to the AgeBasedSalaryStrategy instance.</para>
+ <para>In other words the XML deployment descriptor causes the same sequence of events to occur as if you had written the following code:</para>
+ <programlisting>HRManager hrService = new HRManager();
+AgeBasedSalaryStrategy ageBasedSalary = new AgeBasedSalaryStrategy();
+hrService.setSalaryStrategy(ageBasedSalary);</programlisting>
+ <para>In addition to performing injection via property setter methods JBoss Microcontainer can also perform injection via constructor parameters if necessary. For more details please see the 'Injection' chapter in Part II 'POJO Development'. </para>
+ <note>
+ <para>Although we can create instances of our classes using the <bean> element in the deployment descriptor it is not always appropriate to do so. For example we do not need to create instances of the Employee and Address classes since these will be created by the client. As such they remain part of the service but are not mentioned in the deployment descriptor. </para>
+ <para>Also note that it is possible to define multiple beans within a deployment descriptor provided that each has a unique name. These names are required in order to perform injection as shown above. This does not mean to say however that all of these beans represent services. While a service could be implemented using a single bean it is most often the case that multiple beans are used together as in our example. In these cases there is usually one bean that represents the service entry point containing the public methods intended for the clients to call. In our example this is the HRService bean. Notice that there is nothing in the XML deployment descriptor to say which beans represent a service or indeed which bean if any is the service entry point. Care must therefore be taken when creating deployment descriptors to ensure that sufficient comments are included to describe what the beans are used for. Alternatively a naming convention such as ending each be!
an name that represents a service entry point with 'Service', i.e. HRService can be used instead.</para>
+ </note>
+ </section>
+ <section>
+ <title>Configuring a service</title>
+ <para>Injecting references between POJO instances is one way of configuring a service however we can also inject values into POJO properties. The following deployment descriptor shows how we can configure the HRManager instance to have a hiring freeze and the AgeBasedSalaryStrategy to have new minimum and maximum salary values:</para>
+ <programlisting><?xml version="1.0" encoding="UTF-8"?>
+
+<deployment xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ xsi:schemaLocation="urn:jboss:bean-deployer:2.0 bean-deployer_2_0.xsd"
+ xmlns="urn:jboss:bean-deployer:2.0">
+
+ <bean name="HRService" class="org.jboss.example.service.HRManager">
+ <property name="hiringFreeze">false</property>
+ <property name="salaryStrategy"><inject bean="AgeBasedSalary"/></property>
+ </bean>
+
+ <bean name="AgeBasedSalary" class="org.jboss.example.service.util.AgeBasedSalaryStrategy">
+ <property name="minSalary">1000</property>
+ <property name="maxSalary">80000</property>
+ </bean>
+
+</deployment></programlisting>
+ <para>As with wiring POJOs together the classes need to have public setter methods for the relevant properties so that values can be injected. For example the HRManager class has a <code>setHiringFreeze(boolean hiringFreeze)</code> method and the AgeBasedSalaryStrategy class has <code>setMinSalary(int minSalary)</code> and <code>setMaxSalary(int maxSalary)</code> methods.</para>
+ <para>The values in the deployment descriptor are converted from strings into the relevant types (boolean, integer etc...) by JavaBean <ulink url="http://java.sun.com/j2se/1.5.0/docs/api/java/beans/PropertyEditor.html">PropertyEditors</ulink>. A large number of these are provided by default for standard types but you can easily create your own if necessary. See the Properties chapter in Part II 'POJO Development' for more details.</para>
+ </section>
+ <section>
+ <title>Testing a service</title>
+ <para>We should now have a good idea about how to create POJOs and configure them using an XML deployment descriptor so how do we go about testing them? Thankfully JBoss Microcontainer makes it extremely easy to unit test individual POJOs as well as POJOs that are wired together through the use of a MicrocontainerTest class.</para>
+ <para>The org.jboss.test.kernel.junit.MicrocontainerTest class inherits from junit.framework.TestCase and as such it sets up each test by bootstrapping JBoss Microcontainer and adding a BasicXMLDeployer. It then looks on the classpath for an XML deployment descriptor with the same name as the test class (but ending in .xml) and residing in the same directory structure. Any beans found in this file are deployed and can then be accessed using a convenience method called <code>getBean(String name)</code>. </para>
+ <para>You can see examples of these XML files in the src/test/resources directory:</para>
+ <programlisting>org/jboss/example/service/HRManagerTestCase.xml
+ /HRManagerAgeBasedTestCase.java
+ /HRManagerLocationBasedTestCase.java
+
+org/jboss/example/service/util/AgeBasedSalaryTestCase.xml
+ /LocationBasedSalaryTestCase.xml</programlisting>
+ <para>Our java test source code is located in the src/test/java directory:</para>
+ <programlisting>org/jboss/example/service/HRManagerTestCase.java
+ /HRManagerAgeBasedTestCase.xml
+ /HRManagerLocationBasedTestCase.xml
+ /HRManagerTest.java
+ /HRManagerTestSuite.java
+
+org/jboss/example/service/util/AgeBasedSalaryTestCase.java
+ /LocationBasedSalaryTestVase.java
+ /SalaryStrategyTestSuite.java</programlisting>
+ <para>The HRManagerTest class extends MicrocontainerTest to set up a number of employees to use as the basis for the tests. Individual test cases then subclass this to perform the actual tests. You can also see a couple of TestSuite classes that are used to group individual test cases together for convenience.</para>
+ <para>To run the tests simply enter <code>mvn test</code> from the <code>humanResourcesService/</code> directory. You should see some DEBUG log output which shows JBoss Microcontainer booting up and deploying the relevant XML file before running each test. At the end of the test it then undeploys the file and shuts down the microcontainer.</para>
+ <note>
+ <para>Some of the tests such as HRManagerTestCase, AgeBasedSalaryTestCase and LocationBasedSalaryTestCase simply unit test individual POJOs whilst other tests such as HRManagerAgeBasedTestCase and HRManagerLocationBasedTestCase unit test the whole service consisting of multiple POJOs wired together. Either way the method for conducting the tests remains the same. Thanks to the MicrocontainerTest class it is trivial to set up and conduct comprehensive tests for any part of your code.</para>
+ <para>Finally note that we didn't unit test the Address or Employee classes here. They were deliberately left out as they contain only trivial logic which is very unlikely to break.</para>
+ </note>
+ </section>
+ <section>
+ <title>Packaging a service</title>
+ <para>Now that we have successfully created and tested our service it is time to package it up so that others can use it. The simplest way to do this is to create a JAR containing all of the classes. You can choose to include the XML deployment descriptor if there is a sensible default way to configure the service but you are not required to.</para>
+ <para>If you do choose to include the deployment descriptor then by convention you should call it <code>jboss-beans.xml</code> and put it in the META-INF directory. This helps if you want to later deploy the service in JBoss AS 5 as the default JAR deployer recognises this layout and will automatically deploy the service.</para>
+ <para>In our case we will not include it as we want to easily configure the service in different ways by editing the descriptor directly. To generate a JAR in the <code>target</code> directory containing all of the compiled classes simply enter <code>mvn package</code> from the <code>humanResourcesService/</code> directory. </para>
+ <para>To make the JAR available to other maven projects you then need to enter <code>mvn install</code> in order to copy it to your local maven repository.</para>
+ <para>The final layout of the JAR is as follows:</para>
+ <programlisting>org/jboss/example/service/Address.class
+ /Employee.class
+ /HRManager.class
+org/jboss/example/service/util/AgeBasedSalaryStrategy.class
+ /LocationBasedSalaryStrategy.class
+ /SalaryStrategy.class
+META-INF/MANIFEST.MF
+META-INF/maven/org.jboss.microcontainer.examples/humanResourcesService/pom.xml
+ /pom.properties</programlisting>
+ <para>The META-INF/maven directory is automatically produced by maven and is required so that other maven projects can use this JAR as a dependency. If you are not using maven as your build system then you will not have this directory.</para>
+ </section>
+ </chapter>
+ <chapter>
+ <title>Using services </title>
+ <section>
+ <title>Deploying a service</title>
+ <para>Mention deploying a packaged service vs deploying an unpackaged service.</para>
+ </section>
+ <section>
+ <title>Using the kernel controller</title>
+ <para>This is equivalent to how you access beans using Spring.</para>
+ </section>
+ <section>
+ <title>Using the kernel bus</title>
+ <para>This provides the decoupling we need so that we can swap a service at runtime.</para>
+ </section>
+ <section>
+ <title>Redeploying a service</title>
+ <para>Show here how you can alter the jboss-beans.xml file in the unpackaged service and redeploy the service.</para>
+ </section>
+ <section>
+ <title>Classloading</title>
+ <para>Show how we can remove the ./deploy/humanResourcesService.jar from the classpath and then deploy the jboss-beans.xml file directly in the unpackaged service. We can then configure the <classloader> element of the deployment to point to the classes directory since they won't be available on the Application classpath anymore. We can even move the util package to another directory and show how we can set up a <classloader> element at the bean level.</para>
+ </section>
+ </chapter>
+ <chapter>
+ <title>Adding behaviour through AOP</title>
+ <para/>
+ <para/>
+ <para/>
+ </chapter>
+ <chapter>
+ <title>Advanced deployment</title>
+ <section>
+ <title>Aspectized Deployers </title>
+ <para>Give example of using aspectized bean deployer and show how it's the same as the BasicXMLDeployer.</para>
+ </section>
+ <section>
+ <title>Changing the package structure</title>
+ <para>Give an example where we move the jboss-beans.xml file out of the META-INF directory and change the location of the classes.</para>
+ </section>
+ <section>
+ <title>Changing the XML file format</title>
+ <para>Give an example of changing the jboss-beans.xml file for a jboss-beans.properties file.</para>
+ </section>
+ <section>
+ <title>Changing the classloading strategy</title>
+ </section>
+ <section>
+ <title>Adding a deployment stage</title>
+ </section>
+ </chapter>
+ </part>
+ <part>
+ <title>POJO Development</title>
+ </part>
+ <part>
+ <title>AOP Development</title>
+ </part>
+ <part>
+ <title>Extending the Microcontainer</title>
+ <chapter>
+ <title>Guice Extensions </title>
+ </chapter>
+ <chapter>
+ <title>OSGi Extensions</title>
+ </chapter>
+ <chapter>
+ <title>Drools Extensions</title>
+ </chapter>
+ <chapter>
+ <title>jBPM Extensions</title>
+ </chapter>
+ </part>
+ <part>
+ <title>Integrating the Microcontainer</title>
+ <chapter>
+ <title>JBoss AS</title>
+ <section>
+ <title>Classloading</title>
+ <para>Explain that the default classloading goes to the unified repository.</para>
+ </section>
+ <section>
+ <title>Java EE Deployers</title>
+ </section>
+ <section>
+ <title>MBean Compatibility</title>
+ </section>
+ <section>
+ <title>Managing POJOs</title>
+ </section>
+ </chapter>
+ </part>
+ <appendix>
+ <title>Additional Resources</title>
+ <section>
+ <title>Wiki</title>
+ </section>
+ <section>
+ <title>Forums</title>
+ </section>
+ </appendix>
+</book>
Added: projects/microcontainer/trunk/docs/User_Guide/src/main/images/images/caution.png
===================================================================
(Binary files differ)
Property changes on: projects/microcontainer/trunk/docs/User_Guide/src/main/images/images/caution.png
___________________________________________________________________
Name: svn:mime-type
+ application/octet-stream
Added: projects/microcontainer/trunk/docs/User_Guide/src/main/images/images/documentation.png
===================================================================
(Binary files differ)
Property changes on: projects/microcontainer/trunk/docs/User_Guide/src/main/images/images/documentation.png
___________________________________________________________________
Name: svn:mime-type
+ application/octet-stream
Added: projects/microcontainer/trunk/docs/User_Guide/src/main/images/images/dot.png
===================================================================
(Binary files differ)
Property changes on: projects/microcontainer/trunk/docs/User_Guide/src/main/images/images/dot.png
___________________________________________________________________
Name: svn:mime-type
+ application/octet-stream
Added: projects/microcontainer/trunk/docs/User_Guide/src/main/images/images/dot2.png
===================================================================
(Binary files differ)
Property changes on: projects/microcontainer/trunk/docs/User_Guide/src/main/images/images/dot2.png
___________________________________________________________________
Name: svn:mime-type
+ application/octet-stream
Added: projects/microcontainer/trunk/docs/User_Guide/src/main/images/images/important.png
===================================================================
(Binary files differ)
Property changes on: projects/microcontainer/trunk/docs/User_Guide/src/main/images/images/important.png
___________________________________________________________________
Name: svn:mime-type
+ application/octet-stream
Added: projects/microcontainer/trunk/docs/User_Guide/src/main/images/images/note.png
===================================================================
(Binary files differ)
Property changes on: projects/microcontainer/trunk/docs/User_Guide/src/main/images/images/note.png
___________________________________________________________________
Name: svn:mime-type
+ application/octet-stream
Added: projects/microcontainer/trunk/docs/User_Guide/src/main/images/images/red-bg.png
===================================================================
(Binary files differ)
Property changes on: projects/microcontainer/trunk/docs/User_Guide/src/main/images/images/red-bg.png
___________________________________________________________________
Name: svn:mime-type
+ application/octet-stream
Added: projects/microcontainer/trunk/docs/User_Guide/src/main/images/images/rhlogo.png
===================================================================
(Binary files differ)
Property changes on: projects/microcontainer/trunk/docs/User_Guide/src/main/images/images/rhlogo.png
___________________________________________________________________
Name: svn:mime-type
+ application/octet-stream
Added: projects/microcontainer/trunk/docs/User_Guide/src/main/images/images/shine.png
===================================================================
(Binary files differ)
Property changes on: projects/microcontainer/trunk/docs/User_Guide/src/main/images/images/shine.png
___________________________________________________________________
Name: svn:mime-type
+ application/octet-stream
Added: projects/microcontainer/trunk/docs/User_Guide/src/main/images/images/stock-go-back.png
===================================================================
(Binary files differ)
Property changes on: projects/microcontainer/trunk/docs/User_Guide/src/main/images/images/stock-go-back.png
___________________________________________________________________
Name: svn:mime-type
+ application/octet-stream
Added: projects/microcontainer/trunk/docs/User_Guide/src/main/images/images/stock-go-forward.png
===================================================================
(Binary files differ)
Property changes on: projects/microcontainer/trunk/docs/User_Guide/src/main/images/images/stock-go-forward.png
___________________________________________________________________
Name: svn:mime-type
+ application/octet-stream
Added: projects/microcontainer/trunk/docs/User_Guide/src/main/images/images/stock-go-up.png
===================================================================
(Binary files differ)
Property changes on: projects/microcontainer/trunk/docs/User_Guide/src/main/images/images/stock-go-up.png
___________________________________________________________________
Name: svn:mime-type
+ application/octet-stream
Added: projects/microcontainer/trunk/docs/User_Guide/src/main/images/images/stock-home.png
===================================================================
(Binary files differ)
Property changes on: projects/microcontainer/trunk/docs/User_Guide/src/main/images/images/stock-home.png
___________________________________________________________________
Name: svn:mime-type
+ application/octet-stream
Added: projects/microcontainer/trunk/docs/User_Guide/src/main/images/images/tip.png
===================================================================
(Binary files differ)
Property changes on: projects/microcontainer/trunk/docs/User_Guide/src/main/images/images/tip.png
___________________________________________________________________
Name: svn:mime-type
+ application/octet-stream
Added: projects/microcontainer/trunk/docs/User_Guide/src/main/images/images/warning.png
===================================================================
(Binary files differ)
Property changes on: projects/microcontainer/trunk/docs/User_Guide/src/main/images/images/warning.png
___________________________________________________________________
Name: svn:mime-type
+ application/octet-stream
Added: projects/microcontainer/trunk/docs/User_Guide/src/main/images/images/watermark-alpha1.png
===================================================================
(Binary files differ)
Property changes on: projects/microcontainer/trunk/docs/User_Guide/src/main/images/images/watermark-alpha1.png
___________________________________________________________________
Name: svn:mime-type
+ application/octet-stream
Added: projects/microcontainer/trunk/docs/User_Guide/src/main/images/images/watermark-alpha2.png
===================================================================
(Binary files differ)
Property changes on: projects/microcontainer/trunk/docs/User_Guide/src/main/images/images/watermark-alpha2.png
___________________________________________________________________
Name: svn:mime-type
+ application/octet-stream
Added: projects/microcontainer/trunk/docs/User_Guide/src/main/images/images/watermark-beta1.png
===================================================================
(Binary files differ)
Property changes on: projects/microcontainer/trunk/docs/User_Guide/src/main/images/images/watermark-beta1.png
___________________________________________________________________
Name: svn:mime-type
+ application/octet-stream
Added: projects/microcontainer/trunk/docs/User_Guide/src/main/images/images/watermark-beta2.png
===================================================================
(Binary files differ)
Property changes on: projects/microcontainer/trunk/docs/User_Guide/src/main/images/images/watermark-beta2.png
___________________________________________________________________
Name: svn:mime-type
+ application/octet-stream
Added: projects/microcontainer/trunk/docs/User_Guide/src/main/images/images/watermark-pre-release-candidate.png
===================================================================
(Binary files differ)
Property changes on: projects/microcontainer/trunk/docs/User_Guide/src/main/images/images/watermark-pre-release-candidate.png
___________________________________________________________________
Name: svn:mime-type
+ application/octet-stream
Added: projects/microcontainer/trunk/docs/User_Guide/src/main/images/images/watermark-release-candidate.png
===================================================================
(Binary files differ)
Property changes on: projects/microcontainer/trunk/docs/User_Guide/src/main/images/images/watermark-release-candidate.png
___________________________________________________________________
Name: svn:mime-type
+ application/octet-stream
Added: projects/microcontainer/trunk/docs/User_Guide/src/main/xsl/main-html.xsl
===================================================================
--- projects/microcontainer/trunk/docs/User_Guide/src/main/xsl/main-html.xsl (rev 0)
+++ projects/microcontainer/trunk/docs/User_Guide/src/main/xsl/main-html.xsl 2007-11-15 08:55:33 UTC (rev 67116)
@@ -0,0 +1,249 @@
+<?xml version='1.0'?>
+
+<!--
+ Copyright 2007 Red Hat, Inc.
+ License: GPL
+ Author: Jeff Fearn <jfearn at redhat.com>
+ Author: Tammy Fox <tfox at redhat.com>
+ Author: Andy Fitzsimon <afitzsim at redhat.com>
+-->
+
+<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
+ xmlns:exsl="http://exslt.org/common"
+ version="1.0"
+ exclude-result-prefixes="exsl">
+
+<xsl:import href="http://docbook.sourceforge.net/release/xsl/1.72.0/xhtml/docbook.xsl"/>
+<xsl:import href="http://docbook.sourceforge.net/release/xsl/1.72.0/xhtml/chunk-common.xsl"/>
+<xsl:include href="http://docbook.sourceforge.net/release/xsl/1.72.0/xhtml/chunk-code.xsl"/>
+<xsl:include href="http://docbook.sourceforge.net/release/xsl/1.72.0/xhtml/manifest.xsl"/>
+
+<xsl:include href="redhat.xsl"/>
+<xsl:include href="xhtml-common.xsl"/>
+<xsl:param name="confidential" select="0"/>
+
+<xsl:param name="generate.legalnotice.link" select="1"/>
+<xsl:param name="generate.revhistory.link" select="0"/>
+
+<xsl:param name="chunk.section.depth" select="4"/>
+<xsl:param name="chunk.first.sections" select="1"/>
+<xsl:param name="chunk.toc" select="''"/>
+
+<!--
+From: xhtml/footnote.xsl
+Reason: remove inline css from hr
+Version: 1.72.0
+-->
+<xsl:template name="process.footnotes">
+ <xsl:variable name="footnotes" select=".//footnote"/>
+ <xsl:variable name="table.footnotes" select=".//tgroup//footnote"/>
+
+ <!-- Only bother to do this if there's at least one non-table footnote -->
+ <xsl:if test="count($footnotes)>count($table.footnotes)">
+ <div class="footnotes">
+ <br/>
+ <hr/>
+ <xsl:apply-templates select="$footnotes" mode="process.footnote.mode"/>
+ </div>
+ </xsl:if>
+
+ <xsl:if test="$annotation.support != 0 and //annotation">
+ <div class="annotation-list">
+ <div class="annotation-nocss">
+ <p>The following annotations are from this essay. You are seeing
+ them here because your browser doesn’t support the user-interface
+ techniques used to make them appear as ‘popups’ on modern browsers.</p>
+ </div>
+
+ <xsl:apply-templates select="//annotation" mode="annotation-popup"/>
+ </div>
+ </xsl:if>
+</xsl:template>
+
+<!--
+From: xhtml/chunk-common.xsl
+Reason: remove tables, truncate link text
+Version:
+-->
+<xsl:template name="header.navigation">
+ <xsl:param name="prev" select="/foo"/>
+ <xsl:param name="next" select="/foo"/>
+ <xsl:param name="nav.context"/>
+ <xsl:variable name="home" select="/*[1]"/>
+ <xsl:variable name="up" select="parent::*"/>
+ <xsl:variable name="row1" select="$navig.showtitles != 0"/>
+ <xsl:variable name="row2" select="count($prev) > 0 or (count($up) > 0 and generate-id($up) != generate-id($home) and $navig.showtitles != 0) or count($next) > 0"/>
+ <xsl:if test="$suppress.navigation = '0' and $suppress.header.navigation = '0'">
+ <xsl:if test="$row1 or $row2">
+ <xsl:if test="$row1">
+ <p xmlns="http://www.w3.org/1999/xhtml">
+ <xsl:attribute name="id">
+ <xsl:text>title</xsl:text>
+ </xsl:attribute>
+ <a>
+ <xsl:attribute name="href">
+ <xsl:text>http://www.redhat.com/docs</xsl:text>
+ </xsl:attribute>
+ <strong>
+ <xsl:apply-templates select="." mode="object.title.markup"/>
+ </strong>
+ </a>
+ </p>
+ </xsl:if>
+ <xsl:if test="$row2">
+ <ul class="docnav" xmlns="http://www.w3.org/1999/xhtml">
+ <li class="previous">
+ <xsl:if test="count($prev)>0">
+ <a accesskey="p">
+ <xsl:attribute name="href">
+ <xsl:call-template name="href.target">
+ <xsl:with-param name="object" select="$prev"/>
+ </xsl:call-template>
+ </xsl:attribute>
+ <strong>
+ <xsl:call-template name="navig.content">
+ <xsl:with-param name="direction" select="'prev'"/>
+ </xsl:call-template>
+ </strong>
+ </a>
+ </xsl:if>
+ </li>
+ <li class="next">
+ <xsl:if test="count($next)>0">
+ <a accesskey="n">
+ <xsl:attribute name="href">
+ <xsl:call-template name="href.target">
+ <xsl:with-param name="object" select="$next"/>
+ </xsl:call-template>
+ </xsl:attribute>
+ <strong>
+ <xsl:call-template name="navig.content">
+ <xsl:with-param name="direction" select="'next'"/>
+ </xsl:call-template>
+ </strong>
+ </a>
+ </xsl:if>
+ </li>
+ </ul>
+ </xsl:if>
+ </xsl:if>
+ <xsl:if test="$header.rule != 0">
+ <hr/>
+ </xsl:if>
+ </xsl:if>
+</xsl:template>
+
+<!--
+From: xhtml/chunk-common.xsl
+Reason: remove tables, truncate link text
+Version:
+-->
+<xsl:template name="footer.navigation">
+ <xsl:param name="prev" select="/foo"/>
+ <xsl:param name="next" select="/foo"/>
+ <xsl:param name="nav.context"/>
+ <xsl:param name="title-limit" select="'50'"/>
+ <xsl:variable name="home" select="/*[1]"/>
+ <xsl:variable name="up" select="parent::*"/>
+ <xsl:variable name="row1" select="count($prev) > 0 or count($up) > 0 or count($next) > 0"/>
+ <xsl:variable name="row2" select="($prev and $navig.showtitles != 0) or (generate-id($home) != generate-id(.) or $nav.context = 'toc') or ($chunk.tocs.and.lots != 0 and $nav.context != 'toc') or ($next and $navig.showtitles != 0)"/>
+
+ <xsl:if test="$suppress.navigation = '0' and $suppress.footer.navigation = '0'">
+ <xsl:if test="$footer.rule != 0">
+ <hr/>
+ </xsl:if>
+ <xsl:if test="$row1 or $row2">
+ <ul class="docnav" xmlns="http://www.w3.org/1999/xhtml">
+ <xsl:if test="$row1">
+ <li class="previous">
+ <xsl:if test="count($prev) > 0">
+ <a accesskey="p">
+ <xsl:attribute name="href">
+ <xsl:call-template name="href.target">
+ <xsl:with-param name="object" select="$prev"/>
+ </xsl:call-template>
+ </xsl:attribute>
+ <strong>
+ <xsl:call-template name="navig.content">
+ <xsl:with-param name="direction" select="'prev'"/>
+ </xsl:call-template>
+ </strong>
+ <xsl:variable name="text">
+ <xsl:apply-templates select="$prev" mode="object.title.markup"/>
+ </xsl:variable>
+ <xsl:choose>
+ <xsl:when test="string-length($text) > $title-limit">
+ <xsl:value-of select="concat(substring($text, 0, $title-limit), '...')"/>
+ </xsl:when>
+ <xsl:otherwise>
+ <xsl:value-of select="$text"/>
+ </xsl:otherwise>
+ </xsl:choose>
+ </a>
+ </xsl:if>
+ </li>
+ <xsl:if test="count($up) > 0">
+ <li class="up">
+ <a accesskey="u">
+ <xsl:attribute name="href">
+ <xsl:text>#</xsl:text>
+ </xsl:attribute>
+ <strong>
+ <xsl:call-template name="navig.content">
+ <xsl:with-param name="direction" select="'up'"/>
+ </xsl:call-template>
+ </strong>
+ </a>
+ </li>
+ </xsl:if>
+ <xsl:if test="$home != . or $nav.context = 'toc'">
+ <li class="home">
+ <a accesskey="h">
+ <xsl:attribute name="href">
+ <xsl:call-template name="href.target">
+ <xsl:with-param name="object" select="$home"/>
+ </xsl:call-template>
+ </xsl:attribute>
+ <strong>
+ <xsl:call-template name="navig.content">
+ <xsl:with-param name="direction" select="'home'"/>
+ </xsl:call-template>
+ </strong>
+ </a>
+ </li>
+ </xsl:if>
+ <xsl:if test="count($next)>0">
+ <li class="next">
+ <a accesskey="n">
+ <xsl:attribute name="href">
+ <xsl:call-template name="href.target">
+ <xsl:with-param name="object" select="$next"/>
+ </xsl:call-template>
+ </xsl:attribute>
+ <strong>
+ <xsl:call-template name="navig.content">
+ <xsl:with-param name="direction" select="'next'"/>
+ </xsl:call-template>
+ </strong>
+ <xsl:variable name="text">
+ <xsl:apply-templates select="$next" mode="object.title.markup"/>
+ </xsl:variable>
+ <xsl:choose>
+ <xsl:when test="string-length($text) > $title-limit">
+ <xsl:value-of select="concat(substring($text, 0, $title-limit),'...')"/>
+ </xsl:when>
+ <xsl:otherwise>
+ <xsl:value-of select="$text"/>
+ </xsl:otherwise>
+ </xsl:choose>
+ </a>
+ </li>
+ </xsl:if>
+ </xsl:if>
+ </ul>
+ </xsl:if>
+ </xsl:if>
+</xsl:template>
+
+
+</xsl:stylesheet>
Added: projects/microcontainer/trunk/docs/User_Guide/src/main/xsl/redhat.xsl
===================================================================
--- projects/microcontainer/trunk/docs/User_Guide/src/main/xsl/redhat.xsl (rev 0)
+++ projects/microcontainer/trunk/docs/User_Guide/src/main/xsl/redhat.xsl 2007-11-15 08:55:33 UTC (rev 67116)
@@ -0,0 +1,71 @@
+<?xml version='1.0'?>
+
+<!--
+ Copyright 2007 Red Hat, Inc.
+ License: GPL
+ Author: Jeff Fearn <jfearn at redhat.com>
+ Author: Tammy Fox <tfox at redhat.com>
+ Author: Andy Fitzsimon <afitzsim at redhat.com>
+-->
+
+<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
+ xmlns:exsl="http://exslt.org/common"
+ version="1.0"
+ exclude-result-prefixes="exsl">
+
+<!-- titles after all elements -->
+<xsl:param name="formal.title.placement">
+figure after
+example after
+equation after
+table after
+procedure before
+</xsl:param>
+
+<!--
+Copied from fo/params.xsl
+-->
+<xsl:param name="l10n.gentext.default.language" select="'en'"/>
+
+<!-- This sets the filename based on the ID. -->
+<xsl:param name="use.id.as.filename" select="'1'"/>
+
+<xsl:template match="command">
+ <xsl:call-template name="inline.monoseq"/>
+</xsl:template>
+
+<xsl:template match="application">
+ <xsl:call-template name="inline.boldseq"/>
+</xsl:template>
+
+<xsl:template match="guibutton">
+ <xsl:call-template name="inline.boldseq"/>
+</xsl:template>
+
+<xsl:template match="guiicon">
+ <xsl:call-template name="inline.boldseq"/>
+</xsl:template>
+
+<xsl:template match="guilabel">
+ <xsl:call-template name="inline.boldseq"/>
+</xsl:template>
+
+<xsl:template match="guimenu">
+ <xsl:call-template name="inline.boldseq"/>
+</xsl:template>
+
+<xsl:template match="guimenuitem">
+ <xsl:call-template name="inline.boldseq"/>
+</xsl:template>
+
+<xsl:template match="guisubmenu">
+ <xsl:call-template name="inline.boldseq"/>
+</xsl:template>
+
+<xsl:template match="filename">
+ <xsl:call-template name="inline.monoseq"/>
+</xsl:template>
+
+</xsl:stylesheet>
+
+
Added: projects/microcontainer/trunk/docs/User_Guide/src/main/xsl/xhtml-common.xsl
===================================================================
--- projects/microcontainer/trunk/docs/User_Guide/src/main/xsl/xhtml-common.xsl (rev 0)
+++ projects/microcontainer/trunk/docs/User_Guide/src/main/xsl/xhtml-common.xsl 2007-11-15 08:55:33 UTC (rev 67116)
@@ -0,0 +1,355 @@
+<?xml version='1.0'?>
+
+<!--
+ Copyright 2007 Red Hat, Inc.
+ License: GPL
+ Author: Jeff Fearn <jfearn at redhat.com>
+ Author: Tammy Fox <tfox at redhat.com>
+ Author: Andy Fitzsimon <afitzsim at redhat.com>
+-->
+
+<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
+ xmlns:exsl="http://exslt.org/common"
+ version="1.0"
+ exclude-result-prefixes="exsl">
+
+<!-- Admonition Graphics -->
+<xsl:param name="admon.graphics" select="1"/>
+<xsl:param name="admon.style" select="''"/>
+<xsl:param name="admon.graphics.path">images/</xsl:param>
+<xsl:param name="callout.graphics.path">images/</xsl:param>
+
+<xsl:param name="chunker.output.doctype-public" select="'-//W3C//DTD XHTML 1.0 Strict//EN'"/>
+<xsl:param name="chunker.output.doctype-system" select="'http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd'"/>
+<xsl:param name="chunker.output.encoding" select="'UTF-8'"/>
+<xsl:param name="chunker.output.indent" select="'yes'"/>
+
+<xsl:param name="html.stylesheet" select="'css/rhel.css'"/>
+<xsl:param name="html.stylesheet.type" select="'text/css'"/>
+<xsl:param name="html.cleanup" select="1"/>
+<xsl:param name="html.ext" select="'.html'"/>
+<xsl:output method="html" indent="yes"/>
+
+
+<!-- TOC -->
+<xsl:param name="section.autolabel" select="1"/>
+<xsl:param name="section.label.includes.component.label" select="1"/>
+
+<xsl:param name="generate.toc">
+set toc
+book toc
+article toc
+chapter toc
+qandadiv toc
+qandaset toc
+sect1 nop
+sect2 nop
+sect3 nop
+sect4 nop
+sect5 nop
+section toc
+part toc
+</xsl:param>
+
+<xsl:param name="suppress.navigation" select="0"/>
+<xsl:param name="suppress.header.navigation" select="0"/>
+<xsl:param name="suppress.footer.navigation" select="0"/>
+
+<xsl:param name="header.rule" select="0"/>
+<xsl:param name="footer.rule" select="0"/>
+<xsl:param name="css.decoration" select="0"/>
+<xsl:param name="ulink.target"/>
+<xsl:param name="table.cell.border.style"/>
+
+<!-- BUGBUG TODO
+
+ There is a bug where inserting elements in to the body level
+ of xhtml will add xmlns="" to the tag. This is invalid xhtml.
+ To overcome this I added:
+ xmlns="http://www.w3.org/1999/xhtml"
+ to the outer most tag. This gets stripped by the parser, resulting
+ in valid xhtml ... go figure.
+-->
+
+<!--
+From: xhtml/admon.xsl
+Reason: remove tables
+Version: 1.72.0
+-->
+<xsl:template name="graphical.admonition">
+ <xsl:variable name="admon.type">
+ <xsl:choose>
+ <xsl:when test="local-name(.)='note'">Note</xsl:when>
+ <xsl:when test="local-name(.)='warning'">Warning</xsl:when>
+ <xsl:when test="local-name(.)='caution'">Caution</xsl:when>
+ <xsl:when test="local-name(.)='tip'">Tip</xsl:when>
+ <xsl:when test="local-name(.)='important'">Important</xsl:when>
+ <xsl:otherwise>Note</xsl:otherwise>
+ </xsl:choose>
+ </xsl:variable>
+
+ <xsl:variable name="alt">
+ <xsl:call-template name="gentext">
+ <xsl:with-param name="key" select="$admon.type"/>
+ </xsl:call-template>
+ </xsl:variable>
+
+ <div xmlns="http://www.w3.org/1999/xhtml">
+ <xsl:apply-templates select="." mode="class.attribute"/>
+ <xsl:if test="$admon.style != ''">
+ <xsl:attribute name="style">
+ <xsl:value-of select="$admon.style"/>
+ </xsl:attribute>
+ </xsl:if>
+
+ <xsl:call-template name="anchor"/>
+ <xsl:if test="$admon.textlabel != 0 or title">
+ <h2>
+ <xsl:apply-templates select="." mode="object.title.markup"/>
+ </h2>
+ </xsl:if>
+ <xsl:apply-templates/>
+ </div>
+</xsl:template>
+
+<!--
+From: xhtml/lists.xsl
+Reason: Remove invalid type attribute from ol
+Version: 1.72.0
+-->
+<xsl:template match="substeps">
+ <xsl:variable name="numeration">
+ <xsl:call-template name="procedure.step.numeration"/>
+ </xsl:variable>
+ <xsl:call-template name="anchor"/>
+ <ol xmlns="http://www.w3.org/1999/xhtml" class="{$numeration}">
+ <xsl:apply-templates/>
+ </ol>
+</xsl:template>
+
+<!--
+From: xhtml/lists.xsl
+Reason: Remove invalid type, start & compact attributes from ol
+Version: 1.72.0
+-->
+<xsl:template match="orderedlist">
+ <div xmlns="http://www.w3.org/1999/xhtml">
+ <xsl:apply-templates select="." mode="class.attribute"/>
+ <xsl:call-template name="anchor"/>
+ <xsl:if test="title">
+ <xsl:call-template name="formal.object.heading"/>
+ </xsl:if>
+<!-- Preserve order of PIs and comments -->
+ <xsl:apply-templates select="*[not(self::listitem or self::title or self::titleabbrev)] |comment()[not(preceding-sibling::listitem)] |processing-instruction()[not(preceding-sibling::listitem)]"/>
+ <ol>
+ <xsl:apply-templates select="listitem |comment()[preceding-sibling::listitem] |processing-instruction()[preceding-sibling::listitem]"/>
+ </ol>
+ </div>
+</xsl:template>
+
+<!--
+From: xhtml/lists.xsl
+Reason: Remove invalid type, start & compact attributes from ol
+Version: 1.72.0
+-->
+<xsl:template match="procedure">
+ <xsl:variable name="param.placement" select="substring-after(normalize-space($formal.title.placement), concat(local-name(.), ' '))"/>
+
+ <xsl:variable name="placement">
+ <xsl:choose>
+ <xsl:when test="contains($param.placement, ' ')">
+ <xsl:value-of select="substring-before($param.placement, ' ')"/>
+ </xsl:when>
+ <xsl:when test="$param.placement = ''">before</xsl:when>
+ <xsl:otherwise>
+ <xsl:value-of select="$param.placement"/>
+ </xsl:otherwise>
+ </xsl:choose>
+ </xsl:variable>
+
+<!-- Preserve order of PIs and comments -->
+ <xsl:variable name="preamble" select="*[not(self::step or self::title or self::titleabbrev)] |comment()[not(preceding-sibling::step)] |processing-instruction()[not(preceding-sibling::step)]"/>
+ <div xmlns="http://www.w3.org/1999/xhtml">
+ <xsl:apply-templates select="." mode="class.attribute"/>
+ <xsl:call-template name="anchor">
+ <xsl:with-param name="conditional">
+ <xsl:choose>
+ <xsl:when test="title">0</xsl:when>
+ <xsl:otherwise>1</xsl:otherwise>
+ </xsl:choose>
+ </xsl:with-param>
+ </xsl:call-template>
+ <xsl:if test="title and $placement = 'before'">
+ <xsl:call-template name="formal.object.heading"/>
+ </xsl:if>
+ <xsl:apply-templates select="$preamble"/>
+ <xsl:choose>
+ <xsl:when test="count(step) = 1">
+ <ul>
+ <xsl:apply-templates select="step |comment()[preceding-sibling::step] |processing-instruction()[preceding-sibling::step]"/>
+ </ul>
+ </xsl:when>
+ <xsl:otherwise>
+ <ol>
+ <xsl:attribute name="class">
+ <xsl:value-of select="substring($procedure.step.numeration.formats,1,1)"/>
+ </xsl:attribute>
+ <xsl:apply-templates select="step |comment()[preceding-sibling::step] |processing-instruction()[preceding-sibling::step]"/>
+ </ol>
+ </xsl:otherwise>
+ </xsl:choose>
+ <xsl:if test="title and $placement != 'before'">
+ <xsl:call-template name="formal.object.heading"/>
+ </xsl:if>
+ </div>
+</xsl:template>
+
+<!--
+From: xhtml/graphics.xsl
+Reason: Remove html markup (align)
+Version: 1.72.0
+-->
+<xsl:template name="longdesc.link">
+ <xsl:param name="longdesc.uri" select="''"/>
+
+ <xsl:variable name="this.uri">
+ <xsl:call-template name="make-relative-filename">
+ <xsl:with-param name="base.dir" select="$base.dir"/>
+ <xsl:with-param name="base.name">
+ <xsl:call-template name="href.target.uri"/>
+ </xsl:with-param>
+ </xsl:call-template>
+ </xsl:variable>
+ <xsl:variable name="href.to">
+ <xsl:call-template name="trim.common.uri.paths">
+ <xsl:with-param name="uriA" select="$longdesc.uri"/>
+ <xsl:with-param name="uriB" select="$this.uri"/>
+ <xsl:with-param name="return" select="'A'"/>
+ </xsl:call-template>
+ </xsl:variable>
+ <div xmlns="http://www.w3.org/1999/xhtml" class="longdesc-link">
+ <br/>
+ <span class="longdesc-link">
+ <xsl:text>[</xsl:text>
+ <a href="{$href.to}">D</a>
+ <xsl:text>]</xsl:text>
+ </span>
+ </div>
+</xsl:template>
+
+<!--
+From: xhtml/docbook.xsl
+Reason: Remove inline style for draft mode
+Version: 1.72.0
+-->
+<xsl:template name="head.content">
+ <xsl:param name="node" select="."/>
+ <xsl:param name="title">
+ <xsl:apply-templates select="$node" mode="object.title.markup.textonly"/>
+ </xsl:param>
+
+ <title xmlns="http://www.w3.org/1999/xhtml" >
+ <xsl:copy-of select="$title"/>
+ </title>
+
+ <xsl:if test="$html.stylesheet != ''">
+ <xsl:call-template name="output.html.stylesheets">
+ <xsl:with-param name="stylesheets" select="normalize-space($html.stylesheet)"/>
+ </xsl:call-template>
+ </xsl:if>
+
+ <xsl:if test="$link.mailto.url != ''">
+ <link rev="made" href="{$link.mailto.url}"/>
+ </xsl:if>
+
+ <xsl:if test="$html.base != ''">
+ <base href="{$html.base}"/>
+ </xsl:if>
+
+ <meta xmlns="http://www.w3.org/1999/xhtml" name="generator" content="DocBook {$DistroTitle} V{$VERSION}"/>
+
+ <xsl:if test="$generate.meta.abstract != 0">
+ <xsl:variable name="info" select="(articleinfo |bookinfo |prefaceinfo |chapterinfo |appendixinfo |sectioninfo |sect1info |sect2info |sect3info |sect4info |sect5info |referenceinfo |refentryinfo |partinfo |info |docinfo)[1]"/>
+ <xsl:if test="$info and $info/abstract">
+ <meta xmlns="http://www.w3.org/1999/xhtml" name="description">
+ <xsl:attribute name="content">
+ <xsl:for-each select="$info/abstract[1]/*">
+ <xsl:value-of select="normalize-space(.)"/>
+ <xsl:if test="position() < last()">
+ <xsl:text> </xsl:text>
+ </xsl:if>
+ </xsl:for-each>
+ </xsl:attribute>
+ </meta>
+ </xsl:if>
+ </xsl:if>
+
+ <xsl:apply-templates select="." mode="head.keywords.content"/>
+</xsl:template>
+
+<!--
+From: xhtml/docbook.xsl
+Reason: Add css class for draft mode
+Version: 1.72.0
+-->
+<xsl:template name="body.attributes">
+ <xsl:if test="($draft.mode = 'yes' or ($draft.mode = 'maybe' and ancestor-or-self::*[@status][1]/@status = 'draft'))">
+ <xsl:attribute name="class">
+ <xsl:value-of select="ancestor-or-self::*[@status][1]/@status"/>
+ </xsl:attribute>
+ </xsl:if>
+</xsl:template>
+
+<!--
+From: xhtml/docbook.xsl
+Reason: Add confidential to footer
+Version: 1.72.0
+-->
+<xsl:template name="user.footer.content">
+ <xsl:param name="node" select="."/>
+ <xsl:if test="$confidential = '1'">
+ <h1 xmlns="http://www.w3.org/1999/xhtml" class="confidential">
+ <xsl:text>Red Hat Confidential!</xsl:text>
+ </h1>
+ </xsl:if>
+</xsl:template>
+
+<!--
+From: xhtml/block.xsl
+Reason: default class (otherwise) to formalpara
+Version: 1.72.0
+-->
+<xsl:template match="formalpara">
+ <xsl:call-template name="paragraph">
+ <xsl:with-param name="class">
+ <xsl:choose>
+ <xsl:when test="@role and $para.propagates.style != 0">
+ <xsl:value-of select="@role"/>
+ </xsl:when>
+ <xsl:otherwise>
+ <xsl:text>formalpara</xsl:text>
+ </xsl:otherwise>
+ </xsl:choose>
+ </xsl:with-param>
+ <xsl:with-param name="content">
+ <xsl:call-template name="anchor"/>
+ <xsl:apply-templates/>
+ </xsl:with-param>
+ </xsl:call-template>
+</xsl:template>
+
+<!--
+From: xhtml/block.xsl
+Reason: h5 instead of <b>, remove default title end punctuation
+Version: 1.72.0
+-->
+<xsl:template match="formalpara/title|formalpara/info/title">
+ <xsl:variable name="titleStr">
+ <xsl:apply-templates/>
+ </xsl:variable>
+ <h5 xmlns="http://www.w3.org/1999/xhtml" class="formalpara">
+ <xsl:copy-of select="$titleStr"/>
+ </h5>
+</xsl:template>
+
+</xsl:stylesheet>
More information about the jboss-cvs-commits
mailing list