[Geronimo Wiki] Trivial Update of "Tomcat" by TomMcQueeney

[Apache Wiki <wi...@apache.org>]

Dear Wiki user,

You have subscribed to a wiki page or wiki category on "Geronimo Wiki" for change notification.

The following page has been changed by TomMcQueeney:
http://wiki.apache.org/geronimo/Tomcat

The comment on the change is:
Fixed a couple of typos while reading. No other changes.

------------------------------------------------------------------------------
  
  The Tomcat integration is made up of a set of GBeans that represent the different Tomcat components (i.e. Container, Connectors,  Engine, Host, Valves, etc).  The top level and managing component, the {{{org.apache.geronimo.tomcat.TomcatContainer}}} class is the Tomcat GBean (aka service) of Apache Geronimo.  The integration includes its own Tomcat deployer which allows custom configuration of Tomcat.
  
- The Gbean implementation provides for true integration with Geronimo, allowing Tomcat to fully utilize Geronimo security (JACC/JAAS), transactions, initial contexts, and JNDI.  The Tomcat inteagration currently supports the just mentioned Geronimo functions, but also leverages Tomcat facilities, such as virtual hosts and SSL.
+ The GBean implementation provides for true integration with Geronimo, allowing Tomcat to fully utilize Geronimo security (JACC/JAAS), transactions, initial contexts, and JNDI.  The Tomcat integration currently supports the just mentioned Geronimo functions, but also leverages Tomcat facilities, such as virtual hosts and SSL.
  
  There is one major difference in the Geronimo/Tomcat integration that should be noted.  There are no server.xml or context.xml files.  These have been replaced by the j2ee-server-tomcat-plan.xml and geronimo-tomcat.xml files.  The j2ee-server-tomcat-plan.xml is the equivalent of the server.xml file and contains many of the components that its Tomcat cousin offers, albeit in a different format.  The geronnimo-tomcat.xml file is the equivalent of the context.xml and is used in the web application for runtime deployment and configuration of the web application.
  
  = The j2ee-server-tomcat-plan.xml =
  
- The j2ee-server-tomcat-plan.xml is essentially the equivalent of the server.xml.  In Tomcat the server.xml file is used to describe the Tomcat container configuration for deployment of web aplications.  It allows you to configure the Engine, the Hosts (for virtual hosting), Valves, Realms, etc.  The file is a hierarchical representation of these items in XML format.  The following is an example server.xml file:
+ The j2ee-server-tomcat-plan.xml is essentially the equivalent of the server.xml.  In Tomcat, the server.xml file is used to describe the Tomcat container configuration for deployment of web applications.  It allows you to configure the Engine, the Hosts (for virtual hosting), Valves, Realms, etc.  The file is a hierarchical representation of these items in XML format.  The following is an example server.xml file:
  
  {{{
  <Server port="8005" shutdown="SHUTDOWN">
@@ -112, +112 @@

  
  The dependencies are based on references to other GBeans.  For example, notice the {{{TomcatEngine}}} GBean contains references to the {{{TomcatJAASRealm}}} and the {{{FirstValve}}}.  The Valve chain works in a similar manner.  The Host is also dependent on the Engine, so it contains a reference to the Engine GBean. 
  
- As you can see, the server.xml and j2ee-server-tomcat-plan.xml are similar from a Tomcat object and dependency structure perspective, but they do look different.  Where the server.xml dependencies are based on encapsulating xml objects, the j2ee-server-tomcat-plan.xml uses refrences to other Gbeans.  However, migrating from server.xml to j2ee-server-tomcat-plan.xml should be very simple.  
+ As you can see, the server.xml and j2ee-server-tomcat-plan.xml are similar from a Tomcat object and dependency structure perspective, but they do look different.  Where the server.xml dependencies are based on encapsulating XML objects, the j2ee-server-tomcat-plan.xml uses references to other GBeans.  However, migrating from server.xml to j2ee-server-tomcat-plan.xml should be very simple.  
  
  One area to keep in mind is that there is a main difference between these files, and this is that there is no Context pre-declaration for Geronimo (such as the Contex xml configuration in server.xml).  This is because Geronimo does not support the concept of Stand Alone Tomcat web applications.  This means that all web applications need to be deployed through the deployer, and there is no concept of a "webapps" directory that allows you to pre-declare an application.
  
@@ -141, +141 @@

  
  Don't let the configuration scare you.  Its not as complex as it looks, and the j2ee-server-tomcat-plan.xml file is mostly pre-configured to be used automatically when enabling the Tomcat module.  You will only need to make minor modifications to it (if any).
  
- However, lets take a look at each of the Gbean objects and describe thier configuration in a little more detail for those who wish to dabble in its configuration.
+ However, let's take a look at each of the GBean objects and describe their configuration in a little more detail for those who wish to dabble in its configuration.
  
  == TomcatContainer GBean ==
  
- This GBean is the main service for Tomcat and handles its lifetime within the Geronimo container.  It manages the the major starting and stopping of the Tomcat sub-components.  This GBean is required in order to even use Tomcat in Geronimo. It is not recommended to swap this out with a home-grown version unless a full Geronim infrastructure is supported within the object.  It is recommeneded to leave as-is.
+ This GBean is the main service for Tomcat and handles its lifetime within the Geronimo container.  It manages the major starting and stopping of the Tomcat sub-components.  This GBean is required in order to even use Tomcat in Geronimo. It is not recommended to swap this out with a home-grown version unless a full Geronimo infrastructure is supported within the object.  It is recommeneded to leave as-is.
  
  === Attributes ===
  || '''Attribute''' || '''Required''' || '''Description''' ||
@@ -153, +153 @@

  
  === References ===
  || '''Reference''' || '''Required''' || '''Description''' ||
- || {{{engineGBean}}} || Yes || Reference to the name an {{{EngineGBean}}}. ||
+ || {{{engineGBean}}} || Yes || Reference to the name of an {{{EngineGBean}}}. ||
- || {{{serverInfo}}} || Yes || Reference to a {{{ServerInfo}}} Gbean object. ||
+ || {{{serverInfo}}} || Yes || Reference to a {{{ServerInfo}}} GBean object. ||
  
  == Connector GBean ==
  
@@ -162, +162 @@

  
  === Attributes ===
  || '''Attribute''' || '''Required''' || '''Description''' ||
- || {{{initParams}}} || No || A name/value pair list allowing you to configure parameters for the {{{org.apache.catalina.connector.Connector}}} object (See [http://jakarta.apache.org/tomcat/tomcat-5.5-doc/config/http.html] for specific parameters).  Each name/value pair is separated with a'=', and should be on its own line.||
+ || {{{initParams}}} || No || A name/value pair list allowing you to configure parameters for the {{{org.apache.catalina.connector.Connector}}} object (See [http://jakarta.apache.org/tomcat/tomcat-5.5-doc/config/http.html] for specific parameters).  Each name/value pair is separated with a '=', and should be on its own line.||
  
  
  == Engine GBean ==
  
- This Gbean represents the Engine object in Tomcat and is wrapped and enabled with the {{{EngineGBean}}} object.  It is essentially a wrapper for any type of Engine object.  The {{{TomcatEngine}}}, which is a Geronimo extention on the {{{org.apache.catalina.core.StandardEngine}}} is typically used for this object.  Although nearly any object that extands {{{org.apache.catalina.core.StandardEngine}}} can be used , again, there is some Geronimo based infrastructure that is used to help enable the integration.  It is not recommended to swap this out.
+ This GBean represents the Engine object in Tomcat and is wrapped and enabled with the {{{EngineGBean}}} object.  It is essentially a wrapper for any type of Engine object.  The {{{TomcatEngine}}}, which is a Geronimo extension on the {{{org.apache.catalina.core.StandardEngine}}} is typically used for this object.  Although nearly any object that extends {{{org.apache.catalina.core.StandardEngine}}} can be used , again, there is some Geronimo based infrastructure that is used to help enable the integration.  It is not recommended to swap this out.
  
  === Attributes ===
  || '''Attribute''' || '''Required''' || '''Description''' ||
- || {{{className}}} || Yes || A String represenation of the underlying Engine object.  It is highly recommended to only use the {{{org.apache.geronimo.tomcat.TomcatEngine}}} object||
+ || {{{className}}} || Yes || A String representation of the underlying Engine object.  It is highly recommended to only use the {{{org.apache.geronimo.tomcat.TomcatEngine}}} object||
  || {{{initParams}}} || No || A name/value pair list allowing you to configure parameters for the class declared in the className attribute.  Each name/value pair is separated with a '=', and should be on its own line.||
  
  === References ===
@@ -181, +181 @@

  
  == Host GBean ==
  
- This is the Tomcat Host object GBean wrapped by the {{{HostGbean}}} object.  This is wraps any type of {{{org.apache.catalina.core.StandardHost}}} object.  One or more Host GBeans may be declared.  Each host will represent its own virtual host.  
+ This is the Tomcat Host object GBean wrapped by the {{{HostGbean}}} object.  This wraps any type of {{{org.apache.catalina.core.StandardHost}}} object.  One or more Host GBeans may be declared.  Each host will represent its own virtual host.  
  
  === Attributes ===
  || '''Attribute''' || '''Required''' || '''Description''' ||
- || {{{className}}} || Yes || A String represenation of the underlying Host object.  It is highly recommended to only use the {{{org.apache.catalina.core.StandardHost}}} object, or one that is derived from this object.||
+ || {{{className}}} || Yes || A String representation of the underlying Host object.  It is highly recommended to only use the {{{org.apache.catalina.core.StandardHost}}} object, or one that is derived from this object.||
  ||{{{initParams}}} || No || A name/value pair list allowing you to configure parameters for the class declared in the className attribute.  Each name/value pair is separated with a '=', and should be on its own line.  See [http://jakarta.apache.org/tomcat/tomcat-5.5-doc/config/host.html] for a list of configurable parameters. ||
  
  === References ===
  || '''Reference''' || '''Required''' || '''Description''' ||
- || {{{engineGBean}}} || Yes || The engine GBean name that represents the parent engine for thie host. ||
+ || {{{engineGBean}}} || Yes || The engine GBean name that represents the parent engine for this host. ||
  || {{{realmGBean}}} || No || Reference to a TomcatRealm which will be applied at the Engine level ||
  || {{{TomcatValveChain}}} || No || Reference to the first Valve in a chain of 1 or more valves which will be applied at the Host level ||
  
  == Realm GBean ==
  
- The Realm GBean represents Tomcat Realm objects.  There may be only one realm declared for the Engine and/or Host Gbeans. This GBean may be attached to an Engine, Host, (or Context within the geronimo-tomcat.xml file).
+ The Realm GBean represents Tomcat Realm objects.  There may be only one realm declared for the Engine and/or Host GBeans. This GBean may be attached to an Engine, Host, (or Context within the geronimo-tomcat.xml file).
  
  === Attributes ===
  || '''Attribute''' || '''Required''' || '''Description''' ||
- || {{{className}}} || Yes || A String represenation of the underlying Realm object.||
+ || {{{className}}} || Yes || A String representation of the underlying Realm object.||
  || {{{initParams}}} || No || A name/value pair list allowing you to configure parameters for the class declared in the className attribute.  Each name/value pair is separated with a '=', and should be on its own line.  See [http://jakarta.apache.org/tomcat/tomcat-5.5-doc/config/realm.html] for a list of configurable parameters. ||
  
  == Valve GBean ==
  
- The Valve GBean (yes...you guessed it) represents the Tomcat Valve objects.  This GBean may be attached to an Engine, Host, (or Context within the geronimo-tomcat.xml file).  The Valve object is slightly different from teh other objects in that you chain multiple Valves to preserve order.  The chaining is done by adding a reference to a another Valve within the GBean configuration.
+ The Valve GBean (yes...you guessed it) represents the Tomcat Valve objects.  This GBean may be attached to an Engine, Host, (or Context within the geronimo-tomcat.xml file).  The Valve object is slightly different from the other objects in that you chain multiple Valves to preserve order.  The chaining is done by adding a reference to a another Valve within the GBean configuration.
  
  === Attributes ===
  || '''Attribute''' || '''Required''' || '''Description''' ||
- || {{{className}}} || Yes || A String represenation of the underlying Valve object. ||
+ || {{{className}}} || Yes || A String representation of the underlying Valve object. ||
- ||{{{initParams}}} || No || A name/value pair list allowing you to configure parameters for the class declared in the className attribute.  Each name/value pair is separated with a'=', and should be on its own line.  See [http://jakarta.apache.org/tomcat/tomcat-5.5-doc/config/valve.html] for a list of configurable parameters. ||
+ ||{{{initParams}}} || No || A name/value pair list allowing you to configure parameters for the class declared in the className attribute.  Each name/value pair is separated with a '=', and should be on its own line.  See [http://jakarta.apache.org/tomcat/tomcat-5.5-doc/config/valve.html] for a list of configurable parameters. ||
  
  === References ===
  || '''Reference''' || '''Required''' || '''Description''' ||
@@ -321, +321 @@

  
  = A few words on how it works =
  
- The heart of the module is the GBean itself, which is org.apache.geronimo.tomcat.!TomcatContainer. !TomcatContainer is given a set of deployed webapps that are of org.apache.geronimo.tomcat.!TomcatWebAppContext type. When a webapp is deployed, a configured !WebModuleBuilder is asked for handling it. There're two !WebModuleBuilders: !JettyModuleBuilder and !TomcatModuleBuilder. No matter what builder is used, the idea of deploying the webapp is the same. First, !TomcatModuleBuilder creates a plan (wraps it into !TomcatWebAppContext) and saves it in the repository (a place where configurations are stored). !TomcatWebAppContext's plan contains a reference to !TomcatContainer so that when the context starts up it hands itself over to !TomcatContainer for deployment. It's therefore important to change the module builder if the decision of running Jetty or Tomcat is to be made.
+ The heart of the module is the GBean itself, which is org.apache.geronimo.tomcat.!TomcatContainer. !TomcatContainer is given a set of deployed webapps that are of org.apache.geronimo.tomcat.!TomcatWebAppContext type. When a webapp is deployed, a configured !WebModuleBuilder is asked for handling it. There are two !WebModuleBuilders: !JettyModuleBuilder and !TomcatModuleBuilder. No matter what builder is used, the idea of deploying the webapp is the same. First, !TomcatModuleBuilder creates a plan (wraps it into !TomcatWebAppContext) and saves it in the repository (a place where configurations are stored). !TomcatWebAppContext's plan contains a reference to !TomcatContainer so that when the context starts up it hands itself over to !TomcatContainer for deployment. It's therefore important to change the module builder if the decision of running Jetty or Tomcat is to be made.