Hi David,

   Thanks for your comments.  I will update this "Plugin basics" page based on your thoughts.

    I feel sorry that some documents seem incomplete in the new structure, as we have just restructured the Geronimo 2.2 documents, and started to pull in some content.. 


Ying Tang (Sophia)  

2008/9/18 David Jencks <david_jencks@yahoo.com>
I took a look at this new page and am very sorry to report that I don't think it's an improvement.  While the idea of having a summary page like this seems reasonable much of the content seems to be inaccurate or have unfortunate emphasis:

Plugins are actually system modules. 
- plugins can be system modules, applications, classloader definitions, and plugin groups.  Everything is a plugin in geronimo :-)  I'm reluctant to use both of the terms "module" and "plugin"; module seems to me like it's undefined whereas plugin has a specific meaning in geronimo.  I think what you can safely say is that geronimo servers are assemblages of plugins.
An assembly, then, is a grouping of modules that provides a Geronimo server instance with its feature set.

 Assemblies are the different ways you can create a server out of the various modules available.

 Plugins are very dependent and sensitive to server versions. As such, plugins that are compiled against one server version (like Geronimo 2.1) might not deploy or function correctly in new releases (such as Geronimo 2.1.3). Just as you must redeploy your applications when migrating to updated server releases, you must regenerate any existing plugins for different server levels.
-To the extent this is true it is basically a bug.  We're trying to find ways to keep plugin compatibility between 2.x.* versions.  For instance, we're using artifact aliases in the 2.1.3 release to indicate each plugin can replace the 2.1.2 version.

 Last but not least, when installing plugins you need Internet access so the plugin installer can retrieve all the necessary dependencies from the online repositories.
-No, you need access to plugin repositories that contain the required plugins and libraries.  This can be online, offline, corporate, local, a cd, another geronimo server,.....

Starting with Geronimo 2.2, the servers are assembled entirely out of plugins.

    * Most plugins are modules, describing a classloader and services and possibly containing classes and resources.
    * Plugins also contain descriptive information and include additional instructions on how the plugin fits into a server.
    * Information about multiple plugins can be collected into a plugin catalog, often located in a maven repository
    * A plugin repository is basically a plugin catalog together with a maven-structured repository containing plugins.
    * Plugins can be installed from a plugin repository into an existing Geronimo server using GShell commands or the Geronimo Administration Console.
    * Plugin metadata for an existing plugin in a Geronimo server can be edited (to some extent) in the administrative console.
    * A new server containing a specified set of plugins can be extracted from an existing server using GShell commands or the Geronimo Administration Console.
    * The dependency system assures that the resulting server has all needed plugins to operate.

This list seems badly organized and incomplete to me.  I'd prefer something like this:

What is a plugin?
- plugins have an identifier with groupId, artifactId, version, and type.  (It's possible to have a plugin without a moduleId but this is not currently used)
- a plugin can define a classloader in which case:
-- a plugin with a classloader can define geronimo services (gbeans) that can use classes in the classloader (and its parents)
-- other plugins can depend on this classloader (i.e. have this classloader as a parent).
-- the plugin can contain classes which are made available in the classloader.  This is used mostly for javaee application plugins, where the application classes are packed in the plugin.
- a plugin can contain resources that are unpacked into the server upon installation (typically into the var/ directory in a plugin-specific location)
- a plugin includes a list of dependencies.  This is intended to normally be effectively the same as the classloader dependencies, if there is a classloader.
- a plugin without a classloader definition still includes a list of dependencies.  These are typically used as "plugin groups" to install a set of plugins at once.
Plugins can contain both server functionality and application functionality or both.  For instance, you can include a web server configuration in a web app plugin.

How do I find plugins?
- plugins are listed in plugin catalogs which contain information about the plugins (typically name and description) and where to get the plugin.
- plugins are normally stored in plugin repositories which act much like maven2 repositories.
- The most common examples of plugin repositories are:
-- your local maven repo if you have built geronimo or used maven to package plugins
-- the apache plugin repository containing all the plugins packages by the Apache Geronimo project
-- another geronimo server running the jetty or tomcat plugin-console plugin

How do I install plugins?
- Into an existing server:
-- gshell deploy/list-plugins command
-- admin console
-- using maven and the geronimo-maven-plugin 
- Into a new server assembly using the car-maven-plugin
Note that in all cases the dependency system assure that if you install a plugin, everything needed to run the plugin will also be installed.  For instance if you install a javaee application plugin such as one of the samples into the framework server,  openejb, openjpa, the transaction manager and connector framework and the appropriate web container will also be installed as dependencies.

How do I create plugins?
- As part of a maven build using the car-maven-plugin
- "virtually" by installing a deployed application from a running geronimo server acting as a plugin repository
- using the admin console to create or edit the plugin metadata

How do I assemble a server?
- in a maven build using the car-maven-plugin
- by extracting a server from a running geronimo server using gshell or the admin console.  By specifying the "top level" functions you want such as one or more javaee applications you will also include all the plugins needed to support that functionality such as a web container, openejb, etc etc.

Something that I'd like to see covered in the docs but haven't written myself would be a description of recommended workflow from development through qa to production using plugins, plugin repositories,  and custom assemblies.  IMO this is a lot easier to do using maven but can also be done with other tools, e.g. gshell scripting and use of geronimo servers as plugin repositories.

david jencks

On Sep 17, 2008, at 2:32 AM, Ying Tang wrote:

Hi all,

  I am working together with Rhoda to import the latest updates in 2.1 documentations to 2.2. And  I have updated the "Plugin basics" (http://cwiki.apache.org/confluence/display/GMOxDOC22/Plugin+basics)  page under "Custom server assemblies".

2008/9/11 Rhoda Zheng <rho.zheng@gmail.com>
Hi Jason,

Some contents have been updated already. I will join and work on the rest.  


2008/9/5 Jason Warner <jaw981@gmail.com>

Hi Rhoda,

Will you be moving the content into the new structure as well?


On Thu, Sep 4, 2008 at 9:28 PM, Rhoda Zheng <rho.zheng@gmail.com> wrote:
Hi Joe,

Yes, it works now. The new structure for 2.2 is successfully updated in the space. Thank you.


2008/9/4 Joe Bohn <joe.bohn@earthlink.net>

You should have all of the authorization you need with geronimo-contributors.  It contains everything from geronimo-users plus some.  If you haven't already done so, you should signoff and back on again to pick up the new authorization.

I think we need to remove the geronimo-users group - Does anybody know the purpose of this group anyway?


Rhoda Zheng wrote:
Hi Joe,

Please help grant "geronimo-users" to "Rhoda Zheng" as well. It seems that I can't edit ***Apache Geronimo v2.2* <http://cwiki.apache.org/GMOxDOC22/documentation.html>** docs. Thanks a lot.


2008/9/3 Joe Bohn <joe.bohn@earthlink.net <mailto:joe.bohn@earthlink.net>>

   After finally finding your userid I did add you to the
   geronimo-contributors group.

   Thanks for helping out with the doc.

   Rhoda Zheng wrote:

       Hi Joe,

       My ICLA is on file now. You can find "Wenjing Zheng" in the list
       of ASF Committers. Could you please grant me contributor access
       to the wiki? Thank you very much.


       ---------- Forwarded message ----------
       From: *Rhoda Zheng* <rho.zheng@gmail.com
       <mailto:rho.zheng@gmail.com> <mailto:rho.zheng@gmail.com
       Date: 2008/8/29
       Subject: Re: Geronimo 2.1&2.2 Documentation
       To: dev@geronimo.apache.org <mailto:dev@geronimo.apache.org>
       <mailto:dev@geronimo.apache.org <mailto:dev@geronimo.apache.org>>

       Hi Bill, hi Joe,

       My ICLA is on file now. Thank you very much.


       2008/8/29 bill stoddard <bill@wstoddard.com
       <mailto:bill@wstoddard.com> <mailto:bill@wstoddard.com


          Joe Bohn wrote:

              Hi Rhonda,

              We're glad that you would like to help with the
              Before you can be given contributor access you must first
              an ICLA (Individual Contributor License Agreement) with the
              Apache Software Foundation.  I just checked and I don't see a
              record of an ICLA on file for you yet.  Please let us
       know when
              it is filed and once verified we can grant you contributor
              access to the wiki.

              You can find the form and information on how to submit it at
              this URL:

          Hi Rhoda,
          Here is the link to the ICLA pdf:

          You can submit the form electronically by printing, filling out,
          signing, then scanning it.  Send the scanned and signed form to:

          secretary at apache dot org
          legal-archive at apache dot org

          It will probably take about a week (maybe a bit more due to the
          upcoming labor day holiday) for the ICLA to be recorded by the


~Jason Warner