[jboss-cvs] JBossAS SVN: r66533 - in projects/microcontainer/trunk/docs: User_Guide/en-US and 1 other directory.
jboss-cvs-commits at lists.jboss.org
jboss-cvs-commits at lists.jboss.org
Mon Oct 29 10:38:33 EDT 2007
Author: newtonm
Date: 2007-10-29 10:38:33 -0400 (Mon, 29 Oct 2007)
New Revision: 66533
Added:
projects/microcontainer/trunk/docs/User_Guide/
projects/microcontainer/trunk/docs/User_Guide/en-US/Getting_Started.xml
Removed:
projects/microcontainer/trunk/docs/Getting_Started_Guide/
projects/microcontainer/trunk/docs/User_Guide/en-US/Getting_Started.xml
Log:
Renamed Getting Started Guide to User Guide.
Copied: projects/microcontainer/trunk/docs/User_Guide (from rev 65908, projects/microcontainer/trunk/docs/Getting_Started_Guide)
Deleted: projects/microcontainer/trunk/docs/User_Guide/en-US/Getting_Started.xml
===================================================================
--- projects/microcontainer/trunk/docs/Getting_Started_Guide/en-US/Getting_Started.xml 2007-10-08 12:01:33 UTC (rev 65908)
+++ projects/microcontainer/trunk/docs/User_Guide/en-US/Getting_Started.xml 2007-10-29 14:38:33 UTC (rev 66533)
@@ -1,39 +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>Getting Started 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 Microconainer if you are new to the technology.</para>
- </preface>
- <chapter id="overview">
- <title>Overview</title>
- <para>The Java platform has traditionally been distributed in 3 editions, each providing a different kind of runtime environment: </para>
- <itemizedlist>
- <listitem>
- <para>Java ME - Mobile or other small-scale devices</para>
- </listitem>
- <listitem>
- <para>Java SE - Desktop machines or servers (typically running 2-tier applications)</para>
- </listitem>
- <listitem>
- <para>Java EE - 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 frequent occasions when some are not used.</para>
- <para>Having unused services in your environment is undesirable as they often take up valuable resources such as CPU and memory. They can also clutter up the environment with unecessary configuration files which complicates maintenance and causes confusion. It would therefore be good if there was a controlled way to remove them 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 good if there was a controlled way to add them, again making sure that any dependencies are 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 been deployed. Likewise undeploying a service causes all dependent services to first be undeployed to maintain the integrity of the system. </para>
- <para>As 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>It can even be used to deploy services inside other (non-JBoss) Java EE runtime environments such as WebLogic, Tomcat or Glassfish thanks to it pluggable classloading features. </para>
- <para>Finally JBoss Microcontainer can be used to create services using dependency injection to wire individual POJOs together. Configuration is performed using either XML or annotations depending on where the information is best located. In common with other dependency injection frameworks JBoss Microcontainer can easily be used to create unit tests for POJOs within a service and can also facilitate integration testing of services that depend on each other. </para>
- </chapter>
-</book>
Copied: projects/microcontainer/trunk/docs/User_Guide/en-US/Getting_Started.xml (from rev 66531, projects/microcontainer/trunk/docs/Getting_Started_Guide/en-US/Getting_Started.xml)
===================================================================
--- projects/microcontainer/trunk/docs/User_Guide/en-US/Getting_Started.xml (rev 0)
+++ projects/microcontainer/trunk/docs/User_Guide/en-US/Getting_Started.xml 2007-10-29 14:38:33 UTC (rev 66533)
@@ -0,0 +1,189 @@
+<?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 if you are new to the technology. Part 1 is Getting Started (with multiple chapters), Chapter 2 is Deploying, part 3 is adding behaviour. Don't change examples mid-way through a chapter. </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 however it is often the case that we do not need to use them all.</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 unecessary configuration files which complicates maintenance and causes confusion. It would therefore be good if there was a controlled way to remove them 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 good if there was a controlled way to add them, again making sure that any dependencies are 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 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 to 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 runtime 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>To download JBoss Microcontainer 2.0.0 go to http://labs.jboss.com/jbossmc/downloads and click on the corresponding link.</para>
+ <note>
+ <para>The distribution is available in a number of different packaging formats offering varying levels of compression; tar.gz, tar.bz2 or zip. Simply pick whichever one you have decompression utilities for (e.g. WinZIP on Windows can decompress zip files) and click on the link to download it to your machine.</para>
+ </note>
+ <para> Installation is performed by decompressing and unpacking the downloaded file into a directory on your machine, for example using WinZIP or gzip. The contents of the distribution are as follows:</para>
+ <para>Diagram here....</para>
+ </chapter>
+ <chapter>
+ <title>Building Services</title>
+ <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 change the public method signatures of the class then we can always change its implementation without needing to recompile our client. The 'well-defined' interface in this respect is composed from the public method signatures.</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">different 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 registry 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 different implementations. </para>
+ <para>JBoss Microcontainer provides such a registry 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 can be used in a wide-variety of companies.</para>
+ <section>
+ <title>Creating POJOs</title>
+ <para>Hibernate 115 - (page 114 describes what a POJO is) Mention the bridge to bean through the Java Bean spec.</para>
+ </section>
+ <section>
+ <title>Wiring POJOs together </title>
+ <para>Mention that because all the beans have names, they are by definition services. The fact is that we use a registry for both internal wiring and service registration. So it may be that within the registry there are a large number of beans but you will typically only use a small number of these as the service entry points.</para>
+ </section>
+ <section>
+ <title>Configuring a service</title>
+ </section>
+ <section>
+ <title>Testing a service</title>
+ </section>
+ <section>
+ <title>Packaging a service</title>
+ </section>
+ </chapter>
+ <chapter>
+ <title>Using services </title>
+ <section>
+ <title>Deploying a service</title>
+ </section>
+ <section>
+ <title>Using the kernel registry</title>
+ </section>
+ <section>
+ <title>Swapping a service</title>
+ </section>
+ <section>
+ <title>Using the kernel bus</title>
+ </section>
+ <section>
+ <title>Classloading</title>
+ <para>Give an example of 2 directories on the filesystem and show how we can configure this using 2 different classloaders.</para>
+ </section>
+ </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.</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>
+ <chapter>
+ <title>Adding behaviour through AOP</title>
+ <para>Give examples as follows: Annotation in the class (JDK way), Annotation in XML, plain pointcut expression. The advice is an Audit advice.</para>
+ <para>Follow this with an example that shows how we can declare the AuditAspect as a bean within MC and have a dependency between it and the AuditService class. This means that the AuditAspect will not be deployed until the Audit.jar in is the classpath. This then means that the HRManager service also cannot start since it depends on the AuditAspect.</para>
+ <para>Start chapters with an introduction paragraph. This helps people to learn if they need to read on. Start each section with 'Imagine...'. This catches peoples attention. If you intro simething then you need a summary at the end (ideally in a different way). Don't have one section like 1.2.1, always have a least 2 i.e. 1.2.1 and 1.2.2. Make the chapters and sections balanced. i.e. width ways and length ways. The outer chapters and sections always contain less information than the inner sections. They basically wrap the main content. When you write seques then you need to say what's going to happen without saying what's going to happen.</para>
+ </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>Backwards compatibility with MBeans</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>
More information about the jboss-cvs-commits
mailing list