Return-Path: X-Original-To: apmail-geronimo-scm-archive@www.apache.org Delivered-To: apmail-geronimo-scm-archive@www.apache.org Received: from mail.apache.org (hermes.apache.org [140.211.11.3]) by minotaur.apache.org (Postfix) with SMTP id 5AD464843 for ; Tue, 21 Jun 2011 03:48:47 +0000 (UTC) Received: (qmail 56677 invoked by uid 500); 21 Jun 2011 03:48:47 -0000 Delivered-To: apmail-geronimo-scm-archive@geronimo.apache.org Received: (qmail 56475 invoked by uid 500); 21 Jun 2011 03:48:45 -0000 Mailing-List: contact scm-help@geronimo.apache.org; run by ezmlm Precedence: bulk list-help: list-unsubscribe: List-Post: Reply-To: dev@geronimo.apache.org List-Id: Delivered-To: mailing list scm@geronimo.apache.org Received: (qmail 50945 invoked by uid 99); 21 Jun 2011 03:47:53 -0000 Received: from athena.apache.org (HELO athena.apache.org) (140.211.11.136) by apache.org (qpsmtpd/0.29) with ESMTP; Tue, 21 Jun 2011 03:47:53 +0000 X-ASF-Spam-Status: No, hits=-2000.0 required=5.0 tests=ALL_TRUSTED X-Spam-Check-By: apache.org Received: from [140.211.11.4] (HELO eris.apache.org) (140.211.11.4) by apache.org (qpsmtpd/0.29) with ESMTP; Tue, 21 Jun 2011 03:47:50 +0000 Received: by eris.apache.org (Postfix, from userid 65534) id 77AF32388C7B; Tue, 21 Jun 2011 03:46:27 +0000 (UTC) Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit Subject: svn commit: r1137853 [29/29] - in /geronimo/site/trunk/docs/schemas-3.0: ./ docs/ docs/schemaDiagrams/ Date: Tue, 21 Jun 2011 03:46:22 -0000 To: scm@geronimo.apache.org From: chirunhua@apache.org X-Mailer: svnmailer-1.0.8 Message-Id: <20110621034627.77AF32388C7B@eris.apache.org> Added: geronimo/site/trunk/docs/schemas-3.0/plugins-1.3.xsd URL: http://svn.apache.org/viewvc/geronimo/site/trunk/docs/schemas-3.0/plugins-1.3.xsd?rev=1137853&view=auto ============================================================================== --- geronimo/site/trunk/docs/schemas-3.0/plugins-1.3.xsd (added) +++ geronimo/site/trunk/docs/schemas-3.0/plugins-1.3.xsd Tue Jun 21 03:46:00 2011 @@ -0,0 +1,774 @@ + + + + + + + + + + + + + + + + + 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. + + + + + + + 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. + + + + + + + Influences whether a geronimo plugin is a geronimo plugin group, which is + just a list of other plugins to install. The dependencies listed for this + plugin will be treated as the list of actual plugins to install. + + + + + + + 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 version and container senstive instance of this plugin. + + + + + + + + + + + + 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 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. + + + + + + + + + + Whether the module should be marked load true or false. If marked false it can still + be started if other started modules depend on it. + + + + + + + Optional condition that if present is evaluated to determine whether to load the module. + + + + + + + The "server", i.e. the named set of configuration files, this should be added to. + + + + + + + + + holds key-value pair. key is in 'key' attribute, value is in content + + + + + + + + + key for key-value pair. + + + + + + + The "server", i.e. the named set of configuration files, this should be added to. + + + + + + + + + + + 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 + + + + + + + + + + The import element is restrictive element to + defined type of dependency. The default (when + omitted) is to include the specified dependency + in the classloader (as a parent or URL). If + defined as "classes" means that the classes must + be included in the current module's classloader + but the dependency does not need to be started. + Specifying "services" means that the dependency + (a module) must be started before the current + module, but it is not included as a parent + classloader. + + + + + + + + Influences whether a dependency is marked to start. A plugin is marked to start + in a particular server "instance" primarily based on the load and condition settings in + the config-xml sections. However the start attribute overrides this for plugins installed + as dependencies. + + + + + + + + + + + + + + + + + + The value "classes" means that the classes must be + included in the current module's classloader but the + dependency does not need to be started. + + + + + + + The value "services" means that the dependency (a + module) must be started before the current module, but + it is not included as a parent classloader. + + + + + + + The value "all" means that the dependency (a + module) must be started before the current module, and + it is also included as a parent classloader. + + + + + + + + + + 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. + var/security/keystores/my-keystore + + + + + + + + + Indicates whether the destination is relative to the Geronimo install + directory or the server instance directory (which are the same unless + the server instance is configured). 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 the same as the + Geronimo install dir but may be configured to be elsewhere). + + + + + + + + + + + + + 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. + + + + + + + + + + postgresql + postgresql-8.0-jdbc + 313 + jar + ]]> + + + + + + + + The name for group containing this module. By default, + it is considered 'default' for declaration and wild card + '*' for dependencies. + + + + + + + The name for module in a specified group. All the + artifactId's should be unique within a group. If no + articfactId is provided it will be defaulted to file + name of the module file. + + + + + + + The version number for the module formatted by dot + separated numbers. If no version is provided it will be + defaulted to numeric timestamp generated by + System.currentTimeMillis() at deploy time. In case of + dependencies latest available version will be used. + + + + + + + This element defines the type of the module. The type + could be 'CAR', 'JAR', EAR', 'WAR', etc. If no type is + provided it will be defaulted appropriately by the + deployer depending upon type of deployed module. + + + + + + +