[jboss-cvs] JBossAS SVN: r67249 - projects/microcontainer/trunk/docs/User_Guide/src/main/docbook.
jboss-cvs-commits at lists.jboss.org
jboss-cvs-commits at lists.jboss.org
Mon Nov 19 10:04:01 EST 2007
Author: newtonm
Date: 2007-11-19 10:04:01 -0500 (Mon, 19 Nov 2007)
New Revision: 67249
Modified:
projects/microcontainer/trunk/docs/User_Guide/src/main/docbook/User_Guide.xml
Log:
Refactored introduction and Building services chapters to emphasize services as not necessarily being hot-redeployable.
Modified: projects/microcontainer/trunk/docs/User_Guide/src/main/docbook/User_Guide.xml
===================================================================
--- projects/microcontainer/trunk/docs/User_Guide/src/main/docbook/User_Guide.xml 2007-11-19 14:51:17 UTC (rev 67248)
+++ projects/microcontainer/trunk/docs/User_Guide/src/main/docbook/User_Guide.xml 2007-11-19 15:04:01 UTC (rev 67249)
@@ -36,11 +36,11 @@
<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>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 they are not always all required.</para>
+ <para>Services that are never used are undesirable as they often take up valuable resources such as CPU and memory resulting in lower performance. They may also clutter up the environment with unnecessary configuration files, complicating maintenance and adding unnecessary complexity. Given these drawbacks it would be better if there was a way to create a custom runtime environment containing only those services that were used. You would then be able to create your own custom 'Java Edition' tailored to your requirements.</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 are fully managed 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. You can even redeploy services at runtime providing that you access them via the microcontainer bus.</para>
+ <para>JBoss Application Server 5.0 uses the microcontainer in this way to provide 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. Likewise you are free to remove any services that you don't need simply by changing the server configuration.</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 up 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>
@@ -103,16 +103,16 @@
<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>
+ <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>
+ <para>extending - examples of how we 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>
+ <para>integrating - examples of how JBoss 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>
@@ -126,7 +126,7 @@
<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> 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 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">
@@ -138,10 +138,10 @@
<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>
+ <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 them 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>
+ <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 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>
@@ -149,9 +149,9 @@
<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>
+ <para>The 'well-defined' interface in this respect is composed from the original class's fields and methods 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>
+ <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. This is because the interface ensures that the method signatures do not change.</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>
@@ -172,7 +172,6 @@
/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>
@@ -205,7 +204,7 @@
<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>The Human Resources Service is therefore composed of 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"?>
@@ -230,7 +229,7 @@
xmlns="urn:jboss:bean-deployer:2.0">
<bean name="HRService" class="org.jboss.example.service.HRManager">
- <property name="salaryStrategy"><inject bean="AgeBasedSalary"/></property>
+ <property name="salaryStrategy"><emphasis><inject bean="AgeBasedSalary"/></emphasis></property>
</bean>
<bean name="AgeBasedSalary"
@@ -244,9 +243,11 @@
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>
+ <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 in response to input from the user. As such they remain part of the service but are not mentioned in the deployment descriptor. </para>
</note>
+ <note>
+ <para>Also note that it is possible to define multiple beans within a deployment descriptor providing that each has a unique name. The 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 bea!
n name that represents a service entry point with 'Service' can be used instead, i.e. HRService.</para>
+ </note>
</section>
<section>
<title>Configuring a service</title>
@@ -258,23 +259,22 @@
xmlns="urn:jboss:bean-deployer:2.0">
<bean name="HRService" class="org.jboss.example.service.HRManager">
- <property name="hiringFreeze">false</property>
+ <emphasis><property name="hiringFreeze">false</property></emphasis>
<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>
+ <emphasis><property name="minSalary">1000</property> <property name="maxSalary">80000</property></emphasis>
</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>
+ <para>The values in the deployment descriptor are converted from strings into the relevant types (boolean, int 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>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 (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
@@ -292,7 +292,7 @@
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>The HRManagerTest class extends MicrocontainerTest in order 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>
@@ -302,8 +302,8 @@
<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>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 JAR deployer recognises this layout by default 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 as a separate file. 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
More information about the jboss-cvs-commits
mailing list