geronimo-scm mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From conflue...@apache.org
Subject [CONF] Apache Geronimo v3.0 > Administering plugins
Date Tue, 25 Jan 2011 01:59:00 GMT
<html>
<head>
    <base href="https://cwiki.apache.org/confluence">
            <link rel="stylesheet" href="/confluence/s/2036/9/4/_/styles/combined.css?spaceKey=GMOxDOC30&amp;forWysiwyg=true"
type="text/css">
    </head>
<body style="background: white;" bgcolor="white" class="email-body">
<div id="pageContent">
<div id="notificationFormat">
<div class="wiki-content">
<div class="email">
    <h2><a href="https://cwiki.apache.org/confluence/display/GMOxDOC30/Administering+plugins">Administering
plugins</a></h2>
    <h4>Page <b>edited</b> by             <a href="https://cwiki.apache.org/confluence/display/~maojia508">maojia</a>
    </h4>
        <br/>
                         <h4>Changes (7)</h4>
                                 
    
<div id="page-diffs">
                    <table class="diff" cellpadding="0" cellspacing="0">
    
            <tr><td class="diff-snipped" >...<br></td></tr>
            <tr><td class="diff-unchanged" > <br>h2. Creating a plugin <br></td></tr>
            <tr><td class="diff-changed-lines" >* You can create a plugin as part
of a maven build <span class="diff-added-words"style="background-color: #dfd;">by</span>
using the car-maven-plugin. <br></td></tr>
            <tr><td class="diff-unchanged" >* You can create a plugin &quot;virtually&quot;
by installing a deployed application from a running Geronimo server acting as a plugin repository.
<br></td></tr>
            <tr><td class="diff-changed-lines" >* You can create a plugin <span
class="diff-added-words"style="background-color: #dfd;">by</span> using the Geronimo
administration console to create or edit the plugin metadata. <br></td></tr>
            <tr><td class="diff-unchanged" > <br></td></tr>
            <tr><td class="diff-deleted-lines" style="color:#999;background-color:#fdd;text-decoration:line-through;">By
far the easiest way to build a Geronimo plugin is with maven using the car-maven-plugin. 
Any such module will include a {{geronimo-plugin.xml}} descriptor with at least minimal information.
 When possible, such as the description and license, this information is taken from the pom
itself.  Normally you will build the dependency list from the modules dependencies which are
constructed from the maven dependencies plus whatever additional dependencies the deployers
determine are needed.  For instance an ejb application will have the openejb plugin added
as a dependency by the openejb deployer.  If necessary you can specify the dependencies for
both the module and plugin descriptor explicitly in the car-maven-plugin configuration. <br></td></tr>
            <tr><td class="diff-added-lines" style="background-color: #dfd;">By
far the easiest way to build a Geronimo plugin is with maven using the car-maven-plugin. 
Any such module includes a {{geronimo-plugin.xml}} descriptor with at least minimal information.
 When possible, this information, such as the description and license imformation, is taken
from the pom file itself.  Normally, you will build the dependency list from the modules dependencies
that are constructed from the maven dependencies plus whatever additional dependencies the
deployer determine that are needed.  For instance, an ejb application will have the openejb
plugin added as a dependency by the openejb deployer.  If necessary, you can specify the dependencies
for both the module and plugin descriptor explicitly in the car-maven-plugin configuration.
<br></td></tr>
            <tr><td class="diff-unchanged" > <br>Here&#39;s an example
of a car-maven-plugin configuration using maven dependencies and configuring most of the additional
information possible: <br></td></tr>
            <tr><td class="diff-snipped" >...<br></td></tr>
            <tr><td class="diff-unchanged" >{code} <br> <br></td></tr>
            <tr><td class="diff-changed-lines" >As you use maven to build plugins,
a {{geronimo-plugins.xml}} plugin catalog is automatically maintained in your local maven
repository.  You can force this to be rebuilt by running <span class="diff-added-words"style="background-color:
#dfd;">the following command:</span> <br></td></tr>
            <tr><td class="diff-unchanged" > <br>{code} <br></td></tr>
            <tr><td class="diff-snipped" >...<br></td></tr>
            <tr><td class="diff-unchanged" >Alternatively, you can construct the
{{geronimo-plugin.xml}} file by hand and include it in a deployed module in a geronimo server.
<br> <br></td></tr>
            <tr><td class="diff-changed-lines" >The administration console also
allows limited editing of <span class="diff-added-words"style="background-color: #dfd;">the</span>
{{geronimo-plugin.xml}} <span class="diff-changed-words">files<span class="diff-added-chars"style="background-color:
#dfd;">,</span></span> but editing the information about how the plugin fits
into the server is not yet supported. <br></td></tr>
            <tr><td class="diff-unchanged" > <br> <br>h2. Installing
a plugin <br> <br></td></tr>
            <tr><td class="diff-changed-lines" >If the appropriate administration
console plugin is installed (and your Geronimo server includes Web application <span class="diff-changed-words">support)<span
class="diff-added-chars"style="background-color: #dfd;">,</span></span> you
can install plugins from a plugin repository. After selecting the *Plugins* page from the
navigation <span class="diff-changed-words">menu<span class="diff-added-chars"style="background-color:
#dfd;">,</span></span> select the plugin repository <span class="diff-added-words"style="background-color:
#dfd;">that</span> you want, such as your local maven repository if you have been
building your own plugins.  <span class="diff-changed-words">Next<span class="diff-added-chars"style="background-color:
#dfd;">,</span></span> you <span class="diff-added-words"style="background-color:
#dfd;">will</span> see a list of available plugins from the repository.  Select multiple
plugins using the <span class="diff-changed-words">check<span class="diff-added-chars"style="background-color:
#dfd;"> </span>boxes</span> or a single plugin as a link, and on the next page
you will see more information <span class="diff-deleted-words"style="color:#999;background-color:#fdd;text-decoration:line-through;">on</span>
<span class="diff-added-words"style="background-color: #dfd;">about</span> the
plugins.  On your approval the plugins will be downloaded and installed. <br></td></tr>
            <tr><td class="diff-unchanged" > <br>Alternatively you can use
GShell to install plugins using the *deploy/install-plugin* command. This can be run with
a command line or interactively.  Interactively you can select the plugin repository to use
(if more than one is known), and then select the plugins to install.  Again, they will be
downloaded and installed.  An example of command line usage will be seen as followed:  <br></td></tr>
            <tr><td class="diff-snipped" >...<br></td></tr>
    
            </table>
    </div>                            <h4>Full Content</h4>
                    <div class="notificationGreySide">
        <style type='text/css'>/*<![CDATA[*/
table.ScrollbarTable  {border: none;padding: 3px;width: 100%;padding: 3px;margin: 0px;background-color:
#f0f0f0}
table.ScrollbarTable td.ScrollbarPrevIcon {text-align: center;width: 16px;border: none;}
table.ScrollbarTable td.ScrollbarPrevName {text-align: left;border: none;}
table.ScrollbarTable td.ScrollbarParent {text-align: center;border: none;}
table.ScrollbarTable td.ScrollbarNextName {text-align: right;border: none;}
table.ScrollbarTable td.ScrollbarNextIcon {text-align: center;width: 16px;border: none;}

/*]]>*/</style><div class="Scrollbar"><table class='ScrollbarTable'><tr><td
width='33%' class='ScrollbarPrevName'>&nbsp;</td><td width='33%' class='ScrollbarParent'><sup><a
href="/confluence/display/GMOxDOC30/Deploying+and+administering+plugins"><img border='0'
align='middle' src='/confluence/images/icons/up_16.gif' width='8' height='8'></a></sup><a
href="/confluence/display/GMOxDOC30/Deploying+and+administering+plugins">Deploying and
administering plugins</a></td><td width='33%' class='ScrollbarNextName'>&nbsp;<a
href="/confluence/display/GMOxDOC30/Converting+applications+into+plugins+using+the+Administration+Console">Converting
applications into plugins using the Administration Console</a></td><td class='ScrollbarNextIcon'><a
href="/confluence/display/GMOxDOC30/Converting+applications+into+plugins+using+the+Administration+Console"><img
border='0' align='middle' src='/confluence/images/icons/forwd_16.gif' width='16' height='16'></a></td></tr></table></div>

<h1><a name="Administeringplugins-Administeringplugins"></a>Administering
plugins</h1>
<div>
<ul>
    <li><a href='#Administeringplugins-Administeringplugins'>Administering plugins</a></li>
<ul>
    <li><a href='#Administeringplugins-Creatingaplugin'>Creating a plugin</a></li>
    <li><a href='#Administeringplugins-Installingaplugin'>Installing a plugin</a></li>
    <li><a href='#Administeringplugins-Updatingaplugin'>Updating a plugin</a></li>
<ul>
    <li><a href='#Administeringplugins-Simplejarupgrade'>Simple jar upgrade</a></li>
    <li><a href='#Administeringplugins-Upgradingajarwhilereleasingaplugin'>Upgrading
a jar while releasing a plugin</a></li>
</ul>
</ul>
</ul></div>

<h2><a name="Administeringplugins-Creatingaplugin"></a>Creating a plugin</h2>
<ul>
	<li>You can create a plugin as part of a maven build by using the car-maven-plugin.</li>
	<li>You can create a plugin "virtually" by installing a deployed application from a
running Geronimo server acting as a plugin repository.</li>
	<li>You can create a plugin by using the Geronimo administration console to create
or edit the plugin metadata.</li>
</ul>


<p>By far the easiest way to build a Geronimo plugin is with maven using the car-maven-plugin.
 Any such module includes a <tt>geronimo-plugin.xml</tt> descriptor with at least
minimal information.  When possible, this information, such as the description and license
imformation, is taken from the pom file itself.  Normally, you will build the dependency list
from the modules dependencies that are constructed from the maven dependencies plus whatever
additional dependencies the deployer determine that are needed.  For instance, an ejb application
will have the openejb plugin added as a dependency by the openejb deployer.  If necessary,
you can specify the dependencies for both the module and plugin descriptor explicitly in the
car-maven-plugin configuration.</p>

<p>Here's an example of a car-maven-plugin configuration using maven dependencies and
configuring most of the additional information possible:</p>

<div class="code panel" style="border-width: 1px;"><div class="codeHeader panelHeader"
style="border-bottom-width: 1px;"><b>excerpt from pom.xml</b></div><div
class="codeContent panelContent">
<pre class="code-xml">
<span class="code-tag">&lt;?xml version=<span class="code-quote">"1.0"</span>
encoding=<span class="code-quote">"UTF-8"</span>?&gt;</span>
&lt;project xmlns=<span class="code-quote">"http://maven.apache.org/POM/4.0.0"</span>

         <span class="code-keyword">xmlns:xsi</span>=<span class="code-quote">"http://www.w3.org/2001/XMLSchema-instance"</span>

         xsi:schemaLofcation=<span class="code-quote">"http://maven.apache.org/POM/4.0.0
http://maven.apache.org/maven-v4_0_0.xsd"</span>&gt;

    <span class="code-tag">&lt;modelVersion&gt;</span>4.0.0<span class="code-tag">&lt;/modelVersion&gt;</span>

    <span class="code-tag">&lt;parent&gt;</span>
        <span class="code-tag">&lt;groupId&gt;</span>org.apache.geronimo.plugins<span
class="code-tag">&lt;/groupId&gt;</span>
        <span class="code-tag">&lt;artifactId&gt;</span>plugins<span
class="code-tag">&lt;/artifactId&gt;</span>
        <span class="code-tag">&lt;version&gt;</span>2.2-SNAPSHOT<span
class="code-tag">&lt;/version&gt;</span>
    <span class="code-tag">&lt;/parent&gt;</span>

    <span class="code-tag">&lt;groupId&gt;</span>org.apache.geronimo.configs<span
class="code-tag">&lt;/groupId&gt;</span>
    <span class="code-tag">&lt;artifactId&gt;</span>sharedlib<span
class="code-tag">&lt;/artifactId&gt;</span>
    <span class="code-tag">&lt;name&gt;</span>Geronimo Plugins, Shared
Library<span class="code-tag">&lt;/name&gt;</span>
    <span class="code-tag">&lt;description&gt;</span>Shared Library GBean<span
class="code-tag">&lt;/description&gt;</span>
    <span class="code-tag">&lt;packaging&gt;</span>car<span class="code-tag">&lt;/packaging&gt;</span>

    <span class="code-tag">&lt;build&gt;</span>
        <span class="code-tag">&lt;plugins&gt;</span>
            <span class="code-tag">&lt;plugin&gt;</span>
                <span class="code-tag">&lt;groupId&gt;</span>org.apache.geronimo.buildsupport<span
class="code-tag">&lt;/groupId&gt;</span>
                <span class="code-tag">&lt;artifactId&gt;</span>car-maven-plugin<span
class="code-tag">&lt;/artifactId&gt;</span>
                <span class="code-tag">&lt;configuration&gt;</span>
                    <span class="code-tag">&lt;category&gt;</span>Shared<span
class="code-tag">&lt;/category&gt;</span>
                    <span class="code-tag">&lt;useMavenDependencies&gt;</span>
                        <span class="code-tag">&lt;value&gt;</span>true<span
class="code-tag">&lt;/value&gt;</span>
                        <span class="code-tag">&lt;includeVersion&gt;</span>true<span
class="code-tag">&lt;/includeVersion&gt;</span>
                    <span class="code-tag">&lt;/useMavenDependencies&gt;</span>
                    <span class="code-tag">&lt;instance&gt;</span>
                        <span class="code-tag">&lt;plugin-artifact&gt;</span>
                            <span class="code-tag">&lt;copy-file relative-to=<span
class="code-quote">"server"</span> dest-dir=<span class="code-quote">"var"</span>&gt;</span>shared<span
class="code-tag">&lt;/copy-file&gt;</span>
                        <span class="code-tag">&lt;/plugin-artifact&gt;</span>
                    <span class="code-tag">&lt;/instance&gt;</span>
                <span class="code-tag">&lt;/configuration&gt;</span>
            <span class="code-tag">&lt;/plugin&gt;</span>
        <span class="code-tag">&lt;/plugins&gt;</span>
    <span class="code-tag">&lt;/build&gt;</span>

<span class="code-tag">&lt;/project&gt;</span>

</pre>
</div></div>

<p>As you use maven to build plugins, a <tt>geronimo-plugins.xml</tt> plugin
catalog is automatically maintained in your local maven repository.  You can force this to
be rebuilt by running the following command:</p>

<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
mvn org.apache.geronimo.buildsupport:car-maven-plugin:create-pluginlist
</pre>
</div></div>

<p>This might be necessary if you prune your maven repository and remove plugins listed
in the catalog.</p>

<p>Alternatively, you can construct the <tt>geronimo-plugin.xml</tt> file
by hand and include it in a deployed module in a geronimo server.</p>

<p>The administration console also allows limited editing of the <tt>geronimo-plugin.xml</tt>
files, but editing the information about how the plugin fits into the server is not yet supported.</p>


<h2><a name="Administeringplugins-Installingaplugin"></a>Installing a plugin</h2>

<p>If the appropriate administration console plugin is installed (and your Geronimo
server includes Web application support), you can install plugins from a plugin repository.
After selecting the <b>Plugins</b> page from the navigation menu, select the plugin
repository that you want, such as your local maven repository if you have been building your
own plugins.  Next, you will see a list of available plugins from the repository.  Select
multiple plugins using the check boxes or a single plugin as a link, and on the next page
you will see more information about the plugins.  On your approval the plugins will be downloaded
and installed.</p>

<p>Alternatively you can use GShell to install plugins using the <b>deploy/install-plugin</b>
command. This can be run with a command line or interactively.  Interactively you can select
the plugin repository to use (if more than one is known), and then select the plugins to install.
 Again, they will be downloaded and installed.  An example of command line usage will be seen
as followed: </p>

<p>You can install a plugin into an existing server in different ways:</p>
<ul>
	<li>GShell <a href="/confluence/display/GMOxDOC30/Geronimo+GShell+Commands#GeronimoGShellCommands-Installingaplugin">deploy/install-plugin</a>
command</li>
	<li>Geronimo administrative console</li>
	<li>Using maven and the geronimo-maven-plugin</li>
</ul>


<p>You can also install a plugin into a new server assembly using the car-maven-plugin.<br/>
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 Java EE 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.</p>


<h2><a name="Administeringplugins-Updatingaplugin"></a>Updating a plugin</h2>
<p>At times, you may need to upgrade a plugin or jar version, for instance if a new
version of a dependency is released but you cannot rerelease all the artifacts that depend
on it.  Here are some methods to upgrade jar versions.</p>

<h3><a name="Administeringplugins-Simplejarupgrade"></a>Simple jar upgrade</h3>
<p>If the jar is to be installed as part of a plugin installation, see the section below.
Otherwise, follow these steps. </p>
<ol>
	<li>If the server is running, stop the server.</li>
	<li>Copy the new jar into the appropriate directory in your geronimo server's repository.
 For instance:
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
mkdir -p repository/org/foo/myjar/1.1/
cp ~/newFooJar/myjar-1.1.jar repository/org/foo/myjar/1.1/
</pre>
</div></div>
<p>Alternatively, the administration console portlet <b>Services-&gt;Repository</b>
can be used to add artifacts to the server's repository.</p></li>
</ol>


<p>Finally, after the new jar is installed in the server's repository, add a line to
<tt>var/config/artifact_aliases.properties</tt> (or the equivalent file, if the
server is using a non-standard alias file). For instance, to replace <tt>myjar-1.0.jar</tt>
with <tt>myjar-1.1.jar</tt>:</p>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
org.foo/myjar/1.0/jar=org.foo/myjar/1.1/jar
</pre>
</div></div>
<p>With this configuration, the server will substitute myjar-1.1.jar for any myjar-1.0.jar
dependency.</p>

<h3><a name="Administeringplugins-Upgradingajarwhilereleasingaplugin"></a>Upgrading
a jar while releasing a plugin</h3>
<p>If the jar is installed as part of a plugin installation, you can include configuration
upgrade information in the <tt>geronimo-plugin.xml</tt>. During plugin installation,
the upgraded jar will be automatically installed. This is easiest to specify in the car-maven-config
configuration in the pom.xml, prior to building the plugin.</p>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
&lt;artifact-alias key=<span class="code-quote">"org.foo/myjar/1.0/jar"</span>&gt;org.foo/myjar/1.1/jar&lt;/artifact-alias&gt;
</pre>
</div></div>


    </div>
        <div id="commentsSection" class="wiki-content pageSection">
        <div style="float: right;">
            <a href="https://cwiki.apache.org/confluence/users/viewnotifications.action"
class="grey">Change Notification Preferences</a>
        </div>
        <a href="https://cwiki.apache.org/confluence/display/GMOxDOC30/Administering+plugins">View
Online</a>
        |
        <a href="https://cwiki.apache.org/confluence/pages/diffpagesbyversion.action?pageId=20645472&revisedVersion=2&originalVersion=1">View
Changes</a>
                |
        <a href="https://cwiki.apache.org/confluence/display/GMOxDOC30/Administering+plugins?showComments=true&amp;showCommentArea=true#addcomment">Add
Comment</a>
            </div>
</div>
</div>
</div>
</div>
</body>
</html>

Mime
View raw message