Source code file content

Revision: 5845

JERSEY-1726: updated signature of Jersey TestContainerFactory supports method + copyright update
» Project Revision History

» Checkout URL

svn / trunk / jersey / jersey-documentation / src / docbook / osgi.xml

Size: 9246 bytes, 1 line
<?xml version="1.0" encoding="UTF-8"?>
<!--

    DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.

    Copyright (c) 2010-2013 Oracle and/or its affiliates. All rights reserved.

    The contents of this file are subject to the terms of either the GNU
    General Public License Version 2 only ("GPL") or the Common Development
    and Distribution License("CDDL") (collectively, the "License").  You
    may not use this file except in compliance with the License.  You can
    obtain a copy of the License at
    http://glassfish.java.net/public/CDDL+GPL_1_1.html
    or packager/legal/LICENSE.txt.  See the License for the specific
    language governing permissions and limitations under the License.

    When distributing the software, include this License Header Notice in each
    file and include the License file at packager/legal/LICENSE.txt.

    GPL Classpath Exception:
    Oracle designates this particular file as subject to the "Classpath"
    exception as provided by Oracle in the GPL Version 2 section of the License
    file that accompanied this code.

    Modifications:
    If applicable, add the following below the License Header, with the fields
    enclosed by brackets [] replaced by your own identifying information:
    "Portions Copyright [year] [name of copyright owner]"

    Contributor(s):
    If you wish your version of this file to be governed by only the CDDL or
    only the GPL Version 2, indicate your decision by adding "[Contributor]
    elects to include this software in this distribution under the [CDDL or GPL
    Version 2] license."  If you don't indicate a single choice of license, a
    recipient has the option to distribute your version of this file under
    either the CDDL, the GPL Version 2 or to extend the choice of license to
    its licensees as provided above.  However, if you add GPL Version 2 code
    and therefore, elected the GPL Version 2 license, then the option applies
    only if the new code is made subject to such option by the copyright
    holder.

-->

<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
"http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd"[
<!ENTITY % ents SYSTEM "jersey.ent" >
%ents;
]>
<chapter id="osgi">
  <title>OSGi</title>
  
  <section>
    <title>Feature Overview</title>
  
  <para>OSGi support was added to the Jersey version 1.2. Since then, you should be able to utilize standard OSGi means to run Jersey based web applications
  in OSGi runtime as described in the OSGi Service Platform Enterprise Specification. The specification could be downloaded 
  from <ulink url="http://www.osgi.org/Download/Release4V42">http://www.osgi.org/Download/Release4V42</ulink>.
  </para>
  
  <para>
  The two supported ways of running an OSGi web application are
  <itemizedlist>
    <listitem>WAB (Web Application Bundle)</listitem>
    <listitem>Http Service</listitem>
  </itemizedlist>
  </para>

  <para>
  WAB is in fact just an OSGified WAR archive. Http Service feature allows you to publish Java EE Servlets in the OSGi runtime.
  </para>


  <para>Two examples were added to the Jersey distribution to depict the above mentioned features and show how to use them with Jersey
  <itemizedlist>
    <listitem>
      <para><ulink url="https://maven.java.net/service/local/artifact/maven/redirect?r=&repository;&amp;g=com.sun.jersey.samples&amp;a=helloworld-osgi-webapp&amp;v=&version;&amp;c=project&amp;e=zip">Hello world WAB</ulink></para>
    </listitem>
    <listitem>
      <para><ulink url="https://maven.java.net/service/local/artifact/maven/redirect?r=&repository;&amp;g=com.sun.jersey.samples&amp;a=osgi-http-service&amp;v=&version;&amp;c=project&amp;e=zip">Simple OSGi Http Service application</ulink></para>
    </listitem>
  </itemizedlist>
  Both examples are multi-module maven projects and both consist of an application OSGi bundle module and a test module. The tests are based
  on <ulink url="http://team.ops4j.org/wiki/display/paxexam/Pax+Exam">Pax Exam</ulink> framework.
  Both examples also include a readme file containing instructions how to manually run the application using <ulink url="http://felix.apache.org/site/index.html">Apache Felix</ulink> framework.
  </para>

  <para>
  The rest of the chapter describes how to run the above mentioned examples on <ulink url="http://glassfish.java.net/">GlassFish 3.1.2</ulink> application server.
  Since GlassFish utilizes Apache Felix, an OSGi runtime comes out of the box with GlassFish.
  However, for security reasons, the OSGi shell has been turned off. You can explicitly enable it. Either by starting GlassFish with <code>asadmin -Dglassfish.osgi.start.level.final=3 start-domain</code> or by setting <code>glassfish.osgi.start.level.final</code> property to <code>3</code> in <code>glassfish/config/osgi.properties</code> file.

Presuming you have the default GlassFish instance running, after enabling shell as described above, you should now be able to connect
  to the Felix console with 
<programlisting>
        telnet localhost 6666
</programlisting> 
   You should then see Apache Felix prompt similar to following
<programlisting>
Trying ::1...
Trying 127.0.0.1...
Connected to localhost.
Escape character is '^]'.
____________________________
Welcome to Apache Felix Gogo

g!
</programlisting>

  </para>
  </section>
  
  <section>
    <title>WAB Example</title>
  <para>
  As mentioned above, WAB is just an OSGified WAR archive. Besides the ususal OSGi headers it must in addition contain a special header, <code>Web-ContextPath</code>,
specifying the web application context path. Our WAB has (beside some other) the following headers present in the manifest
  <programlisting>
Web-ContextPath: helloworld
Webapp-Context: helloworld
Bundle-ClassPath: WEB-INF/classes
  </programlisting>
where the second one is ignored by GlassFish, but is needed by other containers not fully compliant with the OSGi Enterprise Specification mentioned above.
The third manifest header worth mentioning is the <code>Bundle-ClassPath</code> specifying where to find the application Java classes within the bundle archive.
</para>
<para>
For more detailed information on the example please see the <ulink url="https://maven.java.net/service/local/artifact/maven/redirect?r=&repository;&amp;g=com.sun.jersey.samples&amp;a=helloworld-osgi-webapp&amp;v=&version;&amp;c=project&amp;e=zip">source code</ulink>.
</para>
<para>
Following is the listing showing how to actually install and run the WAB on GlassFish.  Be sure to replace &lt;version&gt; with the current Jersey version and &lt;repository&gt; with either snapshots or releases based on whether you depend
on a snapshot or stable release version of Jersey respectively:
  <programlisting>g! install https://maven.java.net/service/local/artifact/maven/redirect?r=&lt;repository&gt;&amp;g=com.sun.jersey.samples.helloworld-osgi-webapp&amp;a=war-bundle&amp;v=&lt;version&gt;&amp;e=war
Bundle ID: 246
g! start 246
</programlisting>
In the above listing, the number 246 represents handler to the OSGi bundle you have just installed. Bundle numbers are allocated dynamically.
It means, you might be given a different handler. It is important to always use the correct bundle number as specified by the Felix runtime in the "Bundle ID:" response.
</para>
<para>
After the WAB gets installed and activated by the above mentioned commands, you should be able to access the deployed
Jersey resource at <ulink url="http://localhost:8080/helloworld/webresources/helloworld">http://localhost:8080/helloworld/webresources/helloworld</ulink>
</para>
</section> <!-- END WAB support -->

  <section>
    <title>Http Service Example</title>

  <para>
    OSGi Http Service support currently does not come out of the box with GlassFish, but is provided with a separate OSGi bundle,
    <ulink url="http://search.maven.org/remotecontent?filepath=org/glassfish/osgi-http/3.2-b03/osgi-http-3.2-b03.jar">http://search.maven.org/remotecontent?filepath=org/glassfish/osgi-http/3.2-b03/osgi-http-3.2-b03.jar</ulink>.
    You will need to enable the feature first, by installing that bundle. After that, you can install and activate the Jersey application bundle.
    Following is the listing showing how both bundles could be installed and activated (Be sure to replace &lt;version&gt; with the current Jersey version and &lt;repository&gt; with either snapshots or releases based on whether you depend
on a snapshot or stable release version of Jersey respectively):
    </para>

    <para>
<programlisting>
g! install http://search.maven.org/remotecontent?filepath=org/glassfish/osgi-http/3.2-b03/osgi-http-3.2-b03.jar
Bundle ID: 247
g! install https://maven.java.net/service/local/artifact/maven/redirect?r=&lt;repository&gt;&amp;g=com.sun.jersey.samples.osgi-http-service&amp;a=bundle&amp;v=&lt;version&gt;&amp;e=jar
Bundle ID: 248
g! start 247 248
</programlisting>
Now you should be able to access the Jersey resource at <ulink url="http://localhost:8080/osgi/jersey-http-service/status">http://localhost:8080/osgi/jersey-http-service/status</ulink>
</para>

<para>
Finally, to close the Felix console session just press <code>[Ctrl]-[d]</code>.
</para>
</section> <!-- END HttpService support -->

</chapter>
Terms of Use; Privacy Policy; Copyright ©2013-2015 (revision 20150626.29986a4)
 
 
Close
loading
Please Confirm
Close