[jboss-cvs] JBossAS SVN: r103097 - projects/microcontainer/mcdocs/trunk/userguide/src/main/docbook/en-US.

jboss-cvs-commits at lists.jboss.org jboss-cvs-commits at lists.jboss.org
Mon Mar 29 02:45:09 EDT 2010


Author: misty at redhat.com
Date: 2010-03-29 02:45:08 -0400 (Mon, 29 Mar 2010)
New Revision: 103097

Modified:
   projects/microcontainer/mcdocs/trunk/userguide/src/main/docbook/en-US/Getting_Started.xml
Log:
Reworking Chapter 2


Modified: projects/microcontainer/mcdocs/trunk/userguide/src/main/docbook/en-US/Getting_Started.xml
===================================================================
--- projects/microcontainer/mcdocs/trunk/userguide/src/main/docbook/en-US/Getting_Started.xml	2010-03-29 05:55:43 UTC (rev 103096)
+++ projects/microcontainer/mcdocs/trunk/userguide/src/main/docbook/en-US/Getting_Started.xml	2010-03-29 06:45:08 UTC (rev 103097)
@@ -179,100 +179,101 @@
   </chapter>
   <chapter>
     <title>Building services</title>
-    <para>Before we talk about building services using POJOs it is necessary to define what we
-    mean by these terms.</para>
-    <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&apos;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&apos;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 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
-    &apos;lightweight&apos; form of Java Bean is commonly referred to as simply a
-    &apos;bean&apos; 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 &apos;service&apos; 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 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
-	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. Also clients have to explicitly create a POJO themselves either
-    directly using the <systemitem>new</systemitem> operator or indirectly using a factory. </para>
-    <para>Q) Does a class have to implement an interface in order to provide a
-    &apos;well-defined&apos; interface?</para>
-    <para>A) Not necessarily. Providing that we don&apos;t remove fields or methods from a class,
-    or restrict access to them, we can always change its implementation without needing to
-    recompile any clients. 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 &apos;well-defined&apos; interface in this respect is composed from the original
-    class&apos;s fields and methods together with their access modifiers.</para>
+    <para>
+      Before discussing building services using POJOs let's define some terms.
+    </para>
+    <variablelist>
+      <varlistentry>
+	<term>POJOs</term>
+	<listentry>
+	  <para>
+	    an acronym for Plain Old Java Object, first coined while Rebecca Parsons, Josh MacKenzie, and Martin Fowler 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 do not need to implement a special interfaces. This keeps your code simple allows it to be used in a wider variety of environments. POJOs are also easy to unit test.
+	  </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. This would allow automatic discovery of an object's properties, making it easy to create and populate an instance 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>
+	</listentry>
+      </varlistentry>
+      <varlistentry>
+	<term>Java Bean</term>
+	<listentry>
+	  <para>
+	    a reusable software component that can be manipulated visually in a builder tool. 
+	  </para>
+	  <para>
+	    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: <methodname>get</methodname> and <methodname>set</methodname>. This lightweight form of Java Bean is commonly referred to as a <emphasis>bean</emphasis> and is semantically equivalent to a POJO.
+	  </para>
+	  <note>
+	    <para>
+	      The terms POJO and bean considered to be interchangeable throughout this guide.
+	    </para>
+	  </note>
+	</listentry>
+      </varlistentry>
+      <varlistentry>
+	<term>Services</term>
+	<listentry>
+	  <para>
+	    performs work that is useful to multiple clients, thereby adding to the efficiency of each client.    
+	  </para>
+	  <para>
+	    A service is referenced by a unique name that clients can look up at runtime to gain access. Clients should not have to create the service themselves.
+	  </para>
+	  <para>
+	    Internal changes to a service should not affect any clients. Clients should access a service using a well-defined interface so that the implementation can be changed without having to recompile any clients. In object-oriented programming, this is known as a <emphasis>black box</emphasis>, because to the clients, it does not matter how the service gets its work done.
+	  </para>
+	</listentry>
+      </varlistentry>
+    </variablelist>
+
+    <para>Using ese definitions, let's answer some simple questions:</para>
+    <variablelist>
+      <varlistentry>
+	<term>Is a POJO a service?</term>
+	<listentry>
+	  <para>
+	    No. Although it performs work that is useful to multiple clients, it is not accessed by using a name. Also, clients must explicitly create a POJO themselves, either directly using the <methodname>new</methodname> operator or indirectly using a factory.
+	  </para>
+	</listentry>
+      </varlistentry>
+      <varlistentry>
+	<term>Does a class have to implement an interface in order to provide a well-defined interface?</term>
+	<listentry>
+	  <para>
+	    
+	  </para>
+	</listentry>
+      </varlistentry>
+      <varlistentry>
+	<term></term>
+	<listentry>
+	  <para>
+	    Not necessarily. Providing that you do not remove fields or methods from a class, or restrict access to them, you can always change its implementation without recompiling any clients. 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 <emphasis>well-defined</emphasis> interface in this respect is composed from the original class's fields and methods together with their access modifiers.
+	  </para>
+	</listentry>
+      </varlistentry>
+    </variablelist>
     <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. This is because the interface ensures that the method signatures
-      do not change.</para>
+      <para>
+	Implementing an interface is only necessary when allowing a client to choose between alternative implementations. If the client is compiled against an interface, you can provide as many different implementations of the interface as you like without having to recompile the client. 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 the form of a Controller so
-    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
-    &apos;business-oriented&apos; services. For this reason we shall look at creating,
-    configuring and testing a simple Human Resources service that could potentially be used by a
-    number of different applications.</para>
+
+    <para>
+      What are the steps to create a service using a POJO? First, provide a naming mechanism that allows you to register a reference to the POJO instance with a name. Clients can then look up the POJO reference using the name at runtime and use it to perform work. The POJO class does not need to implement an interface unless the client needs to be able to choose between alternative implementations.
+    </para>
+    <para>
+      JBoss Microcontainer provides such a naming mechanism in the form of a Controller, which is used to deploy POJO services into a runtime environment such as Java SE and look them up from within your applications.
+    </para>
+    <para>
+      Since robust implementations of Java EE services are already available from <ulink url="http://JBoss.org">JBoss.org</ulink> and other communities, it is common for developers to focus on creating more business-oriented services. For this reason, the examples in this guide illustrate creating, configuring, and testing a simple Human Resources service that could potentially be used by a number of different applications.
+    </para>
     <section>
       <title>Creating POJOs</title>
       <para>The example that relates to this section can be found in the




More information about the jboss-cvs-commits mailing list