Schema for a list of Geronimo plugins available at some external site
(namely, a Maven 2 repository).
The geronimo-plugin-list root element is used for the config file present
in the root directory of a Maven repository supporting Geronimo plugin
downloads. This will be scanned by Geronimo clients to determine what
plugins are available on that server.
The geronimo-plugin root element is used as the config file submitted
with an individual Geronimo plugin to the plugin repository. It will be
merged into the plugin list for the repository when the submitted plugin
is accepted.
It is also used for the metadata packed into a plugin when a plugin archive
is downloaded from an online repository for local installation, in which
case it should be packed into the archive at META-INF/geronimo-plugin.xml
The list of plugins available in the current plugin repository.
Each default-repository is a URL to check for any dependencies that
need to be downloaded. Different values can be used, for example, to
host Geronimo plugins at one site and common third-party JARs at
another site, or to maintain a plugin list at a site that is not
actually a repository.
The URL where this fill is downloaded from must list itself as the
first default-repository if it wants to be checked for file
downloads in addition to hosting the plugin list. For every
dnwload, each of the repositories listed here will be checked in
the order listed until the artifact is found. However, if a
plugin in the list includes its own source-repository list, those
repositories will be used instead of these list-level repositories
when downloading that plugin or its dependencies.
Note that while the primary repository may be protected by HTTP
Basic authentication, the backup repositories must either use the
same username and password as the primary or use no authentication.
A human-readable name for this plugin. This will be used to identify
the plugin to a user when giving them a list of plugins to select from.
The Geronimo moduleId for this plugins, which uniquely identifies
it, and also is used to construct a path to download it if necessary.
If no module-id is provided, that means this is a plugin group, which is
just a list of other plugins to install. The prerequisites must still be
met, but then the dependencies listed for this plugin will be treated as
the list of actual plugins to install.
A category name for this plugin. The user interface typically groups
plugins by their category name, so this should match the value for other
plugins in the same category.
A description of this plugin. This will be displayed when the user
looks for more information about this plugin. It typically includes
a description of what it does, what if any third-party software it's
based on, why it would be interesting to use it, etc.
Currently this should be plain text, where whitespace is not significant
except an entirely blank line indicates a paragraph break (like this
documentation, for example). This may change to a more structured format
in the future, if we can agree on what that ought to be.
The URL for a site that contains more detailed information about this
plugin. The plugin repository has access to the basic information
provided in this file, but a plugin may have a home page with more
detailed information, documentation, source code, etc.
Names the author of the plugin. This may be a person, a company, an
open source project, or whatever. Basically, this gives some idea who
submitted the plugin, perhaps where to go for support, etc.
The name of the license that applies to this plugin, usually composed of a
license class (if any) followed by the name and version of a license:
BSD -- Apache Software License (ASL) 2.0
GPL -- Lesser General Public License (LGPL) 2
If there is more than one license listed then that means the user may choose
among any of the available licenses.
Contains a mandatory true/false attribute indicating whether this license
is OSI-approved (e.g. whether the plugin is open source).
Note that the license declared here applies only to the current component.
Any dependencies may be licensed separately.
A hash value (typically MD5 or SHA-1) that applies to the plugin download
file. This can be used to confirm that a plugin download was complete, and
to ensure that the file downloaded is the same as the file originally
posted to the repository.
Indicates a version of the Geronimo base server that this plugin can run in.
If no geronimo-version is listed, that means the plugin can run in any version
of Geronimo so long as the prerequisites, parents, and dependencies are present.
If one or more geronimo-version elements are listed, then the current version of
Geronimo must match one of them in order for this plugin to be installable.
This is applied as an exact match: 1.2 does not match 1.2.1 or 1.2-SNAPSHOT
Indicates a version of the JVM that this plugin can run in. If no jvm-version
is listed, that means the plugin can run in any version of the JVM supported
by Geronimo so long as the prerequisites, parents, and dependencies are present.
If one or more jvm-version elements are listed, then the JVM that Geronimo is
currently running on must match one of them in order for this plugin to be
installable. (It does not stop you from restarting Geronimo on a different JVM
version once the components is already installed.)
This is not normally used, but must be for plugins that use CORBA or
serialized QNames, etc.
This is applied as a prefix match: 1.4 matches 1.4.2 or 1.4.2_10
A dependency of this plugin that must be previously installed if this
plugin is to be considered to be installable. This is generally the
same as the dependency element (for example, it may refer to a plugin
by moduleId or a JAR by repository ID) except that the dependency will not
be downloaded on demand and must have been previously installed.
This is currently used for a web application to specify the web container it
runs in (so we don't show Tomcat downloads for a Jetty installation, etc.). It
may be used for similar things in the future if more distribution choices are
added to Geronimo.
It is also used by the public Geronimo plugin repository in cases where the
dependencies cannot be redistributed (e.g. a dependency on a commercial JDBC
driver JAR which must be manually acquired and installed).
It is also used when a user must set something up (like a database pool or
security realm) to point to a custom resource in their environment before the
plugin can be installed.
This is applied as an exact match, except that the version number may be
omitted, in which case any matching version of the dependency will work.
It has an optional resource-type attribute indicating to the user what type
of prerequisite this is (for cases where they're expected to set something up
as opposed to just downloading a JAR). e.g. it could be set to "JDBC Pool".
Likewise there is an option description to provide more detailed guidance for
how to resolve the prerequisite.
The moduleId of another plugin or Geronimo module, or the repository ID of
a 3rd party JAR that this plugin depends on. That means that the dependency
must be downloaded and installed if this plugin is selected.
This is applied as an exact match, except that the version number may be
omitted, in which case any matching version of the dependency will work.
The moduleId of another plugin or Geronimo module that this plugin replaces.
That can be used, for example, to replace a less functional module
with a more functional one, or to upgrade a component to a newer version.
This is applied as an exact match, except that the version number may be
omitted, in which case any matching version of the module or plugin will be
replaced. Be aware that omitting the version number may cause a
plugin to be downgraded, so you may choose to explicitly list all
lesser versions. That may not be desirable either, though. If the
server has foo-1.0.2 installed and you install foo-1.0.1, would you
rather have it downgrade or end up with both installed?
NOTE: currently the "obsoletes" entries are only processed on the
plugin(s) passed directly to the PluginInstaller (not on dependencies that
are brought down as a result). That means that a plugin group must list
obsoletes for all its components, etc.
The base URL for the repository that this plugin should be downloaded from.
The repositories listed here will be consulted in the order listed every
time something needs to be downloaded, and the search will stop at the
first repository that holds any matching plugin or JAR.
In a normal plugin list, the repositories are specified at the list level,
and do not need to be repeated at the plugin level. However, any values
specified at the plugin level replace the values specified at the list
level. This can be used to maintain a single list of plugins from multiple
sources.
This value is required if this is not a plugin list but metadata for a
single plugin included in a plugin file downloaded from a repository.
Otherwise, the installer would not know where to download any dependencies
from.
Lets a plugin include files that should be copied into the Geronimo
installation tree, beyond copying the plugin into the repository. For
example, this could be used to copy files into geronimo/bin, geronimo/lib,
geronimo/var/security/keystores, or other Geronimo dirs.
Lets a plugin declare data that should be inserted into config.xml
when the plugin is installed. This is normally used to add ports
and other settings that the user is likely to want to change. The
gbean entries declared here will be written into config.xml for the
new module when the plugin is installed.
See pluginType/license above
Indicates whether this license is OSI-approved, which is to say, whether
the plugin is open source. Typically this is true for all licenses
you'd expect to be open source, and false for proprietary plugins.
If there's some doubt, visit http://www.opensource.org/licenses/index.php
See pluginType/dependency above
Normally when a plugin dependency is installed it will not
be started. The user may be prompted to start the plugin
with whatever tool kicked off the install to begin with.
This attribute may be set to "true" to force the plugin to
be started after it is installed. NOTE: this currently only
affects the dependencies of the plugins actually passed to
the PluginInstaller (not nested dependencies). This
means it's primarily useful for plugin lists.
See pluginType/hash above
Indicates the type of hash. The values presently supported are:
MD5
SHA-1
The name of a file in the plugin archive that should be copied into
the server installation tree somewhere when the plugin is installed.
There may be a path component (relative to the root of the plugin
archive), though that will not be used to construct the destination
location. For example:
resources/keystores/my-keystore
This will copy the file resources/keystores/my-keystore to e.g.
geronimo/var/security/keystores/my-keystore
Indicates whether the destination is relative to the Geronimo install
directory or the server instance var/ directory. The values presently
supported are:
geronimo
server
The directory to copy the file to, relative to either the Geronimo
install dir or the server's home directory (normally var/ but may
vary).
The Module ID of the prerequisite. This is used to check whether
it's available on the server that you're downloading the plugin
into. It may omit some portions of the Module ID to be more
accomodating (e.g. "*/MyDBPool/*/*" to identify a database pool
instead of "console/MyDBPool/1.0/car").
Note that the values here may take the non-standard syntax of
* instead of the empty string for a missing value, which will
hopefully make the wildcard format more user-friendly.
(On the theory that "Please install */MyDBPool/*/*" should make
more sense than "Please install /MyDBPool//" for an average user)
Describes the type of resource that the prerequisite is. Examples
include:
JDBC Driver
JDBC Pool
JMS Resource Group
JavaMail
This is mainly used for prerequisites where the user needs to set
something up and you want to indicate what. So for example, you
could say "console/myapp-pool/*/jar" is a prerequisite with resource
type "JDBC Pool" and then the user should understand that they can
install your plugin if they create a JDBC pool called "myapp-pool"
in the console, or manually deploy a pool with moduleId
"console/myapp-pool/(something)/jar"
Another option in that case would be to use a dependency on a JDBC
pool plugins you provide, but then it would have to use the
system database (and run a DDL script on the first connect) in order
to be installable in an arbitrary Geronimo server. That would be a
better approach for demonstration applications, whereas the
prerequisite on a user-installed pool would be a better approach for
production applications.
A description for the user about why this is a prerequisite and what
they should do to set it up. Here are a couple examples:
This plugin of SomeApp is configured for the Jetty version of
Geronimo. It cannot be installed on the Tomcat version of Geronimo.
There's a separate plugin for the Tomcat version of Geronimo.
SomeApp requires a database connection pool. Supported databases
are PostgreSQL and MySQL. Please configure a database connection
pool with the name "SomeAppPool" and then run the associated create
script from http://someapp.com/db-scripts/ before installing this
plugin.