You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@clerezza.apache.org by re...@apache.org on 2009/12/19 20:26:11 UTC
svn commit: r892501 - in /incubator/clerezza:
issues/CLEREZZA-43/org.apache.clerezza.triaxrs/
trunk/org.apache.clerezza.parent/org.apache.clerezza.triaxrs/
trunk/org.apache.clerezza.parent/org.apache.clerezza.triaxrs/org.apache.clerezza.triaxrs/src/sit...
Author: reto
Date: Sat Dec 19 19:26:11 2009
New Revision: 892501
URL: http://svn.apache.org/viewvc?rev=892501&view=rev
Log:
CLEREZZA-43: closed
Removed:
incubator/clerezza/issues/CLEREZZA-43/org.apache.clerezza.triaxrs/
Modified:
incubator/clerezza/trunk/org.apache.clerezza.parent/org.apache.clerezza.triaxrs/ (props changed)
incubator/clerezza/trunk/org.apache.clerezza.parent/org.apache.clerezza.triaxrs/org.apache.clerezza.triaxrs/src/site/xsite/content/howto_prefix.xhtml
incubator/clerezza/trunk/org.apache.clerezza.parent/org.apache.clerezza.triaxrs/org.apache.clerezza.triaxrs/src/site/xsite/content/tutorial_1.xhtml
Propchange: incubator/clerezza/trunk/org.apache.clerezza.parent/org.apache.clerezza.triaxrs/
------------------------------------------------------------------------------
--- svn:mergeinfo (added)
+++ svn:mergeinfo Sat Dec 19 19:26:11 2009
@@ -0,0 +1 @@
+/incubator/clerezza/issues/CLEREZZA-43/org.apache.clerezza.triaxrs:891792-892499
Modified: incubator/clerezza/trunk/org.apache.clerezza.parent/org.apache.clerezza.triaxrs/org.apache.clerezza.triaxrs/src/site/xsite/content/howto_prefix.xhtml
URL: http://svn.apache.org/viewvc/incubator/clerezza/trunk/org.apache.clerezza.parent/org.apache.clerezza.triaxrs/org.apache.clerezza.triaxrs/src/site/xsite/content/howto_prefix.xhtml?rev=892501&r1=892500&r2=892501&view=diff
==============================================================================
--- incubator/clerezza/trunk/org.apache.clerezza.parent/org.apache.clerezza.triaxrs/org.apache.clerezza.triaxrs/src/site/xsite/content/howto_prefix.xhtml (original)
+++ incubator/clerezza/trunk/org.apache.clerezza.parent/org.apache.clerezza.triaxrs/org.apache.clerezza.triaxrs/src/site/xsite/content/howto_prefix.xhtml Sat Dec 19 19:26:11 2009
@@ -18,7 +18,120 @@
* specific language governing permissions and limitations
* under the License.
*/
---></i></p>
+-->
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
+<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en-us">
+ <head>
+ <title>How to Configure the Path Prefix of a Resource Bundle</title>
+ </head>
+ <body>
+ <h1>How to Configure the Path Prefix of a Resource Bundle</h1>
+ <p>Author: Manuel - clerezza.org</p>
+ <p>Date: November 20, 2008</p>
+ <h2>Table of Contents</h2>
+ <p>
+ <a href="#intro">1. Introduction</a>
+ </p>
+ <p>
+ <a href="#defaultprefix">2. Setup the Default Prefix in the Resource Bundle</a>
+ </p>
+ <p>
+ <a href="#customprefix">3. Define a Custom Prefix for a Resource Bundle</a>
+ </p>
+ <p>
+ <a href="#references">4. References</a>
+ </p>
+ <h2 id="intro">1. Introduction</h2>
+
+ <p> A resource is annotated with the <code>@Path</code> annotation, which
+ specifies where the resource is found. The path value is after compilation hard to change,
+ but it is maybe for desirable the user of that resource to modifiy that path.
+ Therefore Triaxrs offers the possibility to prepend a path prefix
+ to all resources of a resource bundle. A resource bundle is a bundle that provides
+ a <code>javax.ws.rs.core.Application</code> or individual resources, both are marked
+ with the service property set <code>javax.ws.rs=true</code>. </p>
+ <p> Triaxrs supports two ways to modify the path prefix of a resource bundle: </p>
+ <ul>
+ <li>The developer of a resource bundle has the option to define a default path prefix
+ in the bundle manifest.</li>
+ <li>The user of the bundle can change/define the path prefix over the Triaxrs Prefix
+ Manager service.</li>
+ </ul>
+
+ <h2 id="defaultprefix">2. Setup the Default Prefix in the Resource Bundle</h2>
+
+ <p> The default path prefix is defined by the developer of that bundle. The prefix
+ can be defined directly in the bundle manifest using the "Triaxrs-PathPrefix"-header
+ or through the pom.xml in the configuration of the maven-bundle-plugin.
+ Here is an example how the header looks in the bundle manifest: </p>
+ <pre><code>
+ Triaxrs-PathPrefix: /myprefix
+ </code></pre>
+ <p>
+
+ The following is an example how the default path prefix configuration is done
+ in the pom.xml:
+ </p>
+ <pre><code>
+ ...
+ <plugin>
+ <groupId>org.apache.felix</groupId>
+ <artifactId>maven-bundle-plugin</artifactId>
+ <extensions>true</extensions>
+ <configuration><strong>
+ <instructions>
+ <Triaxrs-PathPrefix>/myprefix</Triaxrs-PathPrefix>
+ </instructions></strong>
+ </configuration>
+ </plugin>
+ ...
+ </code></pre>
+
+ <p> The following resource in the bundle with the above prefix would be reachable
+ under the path "/myprefix/contact/". </p>
+ <pre><code>
+ package org.example.clerezza.tutorial1;
+
+ import javax.ws.rs.GET;
+ import javax.ws.rs.Path;
+ import javax.ws.rs.QueryParam;
+
+ @Path("/contact") // sets the path for this service
+ public class App {
+
+ Person[] persons;
+ public App() {
+ persons = new Person[3];
+ persons[0] = new Person("Jane", "Roe");
+ persons[1] = new Person("Richard", "Roe");
+ persons[2] = new Person("John", "Doe");
+ }
+
+ @GET // this method process GET requests
+ public Person getPerson(@QueryParam("id") int id) {
+ return persons[id];
+ }
+ }
+ </code></pre>
+ <h2 id="customprefix">3. Define a Custom Prefix for a Resource Bundle</h2>
+ <p> The default path prefix is "hard-coded" in the bundle and is hence for the
+ bundle user hard to change. Therefore Triaxrs provides the Triaxrs Prefix
+ Manager service which gives the user the opportunity to customize path prefixes.
+ When a resource bundle is bound to the <code>org.clerezza.triaxrs.JaxRsHandler</code>
+ service, it will look up if a prefix is defined. For this the Triaxrs Prefix Manager
+ maintains a mapping between a bundles symoblic name and its prefix. The user can modify
+ this mapping over the configuration admin service[<a href="#note-1">1</a>].
+ This allows that the Triaxrs Prefix Manager can be configured over a configuration user interface
+ like for example Felix's OSGi Management Console.</p>
+ <p> It is also possible to activate or deactivate the usage of the default and custom
+ prefixes. This can be done by setting the service properties "Triaxrs-UseDefaultPrefix" and
+ "Triaxrs-UseCustomPrefix" of the Triaxrs Prefix Manager. They can be set to
+ <code>true</code> or <code>false</code>. By default prefixes are used. </p>
+
+ <h2 id="references">4. References</h2>
+ <p id="ref1">[1] OSGi Service Platform, Service Compendium, Release 4, Version 4.1, OSGi Alliance., 2007, chap. 104. , ISBN 978-90-79350-02-5</p>
+
+ <p><i>That's all folks for this time! <br/><!--You can send your feedback to: --></i></p>
</body>
</html>
Modified: incubator/clerezza/trunk/org.apache.clerezza.parent/org.apache.clerezza.triaxrs/org.apache.clerezza.triaxrs/src/site/xsite/content/tutorial_1.xhtml
URL: http://svn.apache.org/viewvc/incubator/clerezza/trunk/org.apache.clerezza.parent/org.apache.clerezza.triaxrs/org.apache.clerezza.triaxrs/src/site/xsite/content/tutorial_1.xhtml?rev=892501&r1=892500&r2=892501&view=diff
==============================================================================
--- incubator/clerezza/trunk/org.apache.clerezza.parent/org.apache.clerezza.triaxrs/org.apache.clerezza.triaxrs/src/site/xsite/content/tutorial_1.xhtml (original)
+++ incubator/clerezza/trunk/org.apache.clerezza.parent/org.apache.clerezza.triaxrs/org.apache.clerezza.triaxrs/src/site/xsite/content/tutorial_1.xhtml Sat Dec 19 19:26:11 2009
@@ -18,7 +18,644 @@
* specific language governing permissions and limitations
* under the License.
*/
---></i></p>
+-->
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
+<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en-us">
+ <head>
+ <title>Tutorial 1: Developing a RESTful Web Application for OSGi Runtime Environment</title>
+ </head>
+ <body>
+ <h1>Tutorial 1: Developing a RESTful Web Application for OSGi
+ Runtime Environment</h1>
+ <p>Author: Hasan - clerezza.org</p>
+ <p>Date: October 9, 2008</p>
+ <p>Contributor: Reto BG, Tsuyoshi Ito - clerezza.org</p>
+ <h2>Table of Contents</h2>
+ <p>
+ <a href="#objective">1. Objective</a>
+ </p>
+ <p>
+ <a href="#initialization">2. Initializing a Maven Project</a>
+ </p>
+ <p>
+ <a href="#functionality">3. Implementing the Functionality</a>
+ </p>
+ <p>
+ <a href="#root_resource">4. Making a Class a JAX-RS Root Resource</a>
+ </p>
+ <p>
+ <a href="#representation">5. Getting the Representation of a Resource</a>
+ </p>
+ <p>
+ <a href="#bundling">6. Configuring Packaging Type and Plugin for Bundling</a>
+ </p>
+ <p>
+ <a href="#declarative_service">7. Using OSGi Declarative Service</a>
+ </p>
+ <p>
+ <a href="#build">8. Building Tutorial1 Bundle</a>
+ </p>
+ <p>
+ <a href="#deploy">9. Deploying and Starting the Bundle in an OSGi Container
+ </a>
+ </p>
+ <p>
+ <a href="#service_access">10. Accessing the Web Service</a>
+ </p>
+ <p>
+ <a href="#references">11. References</a>
+ </p>
+ <h2 id="objective">1. Objective</h2>
+ <p>
+ In this tutorial you will learn how to write a RESTful [
+ <a href="#ref1">1</a>
+ ] Web application running in an OSGi [
+ <a href="#ref2">2</a>
+ ] container. One key advantage of applying REST principles in
+ developing a Web application is the simpler implementation of a
+ service, since interactions are stateless. Statelessness also leads
+ to a better server scalability (cf. Section 5.1.3 of [
+ <a href="#ref1">1</a>
+ ]). The use of OSGi technology offers a modular implementation of an
+ application through its component model. Each component (in the form
+ of a bundle) can be dynamically deployed and replaced without the
+ need to take the application down. A bundle is a tightly-coupled,
+ dynamically loadable collection of classes, jars, and configuration
+ files.
+ </p>
+ <p>
+ The example OSGi bundle to be developed allows for the retrieval of
+ personal data by specifying an identification number (ID). Thus, the
+ Web application provides for a personal data retrieval service.
+ Depending on the ID in the URI of a Web request, the corresponding
+ personal data are returned in the Web response. For the sake of
+ simplicity, the personal data in this tutorial consist only of
+ firstname and lastname. The time it takes to go through this tutorial
+ is around 30 minutes. This tutorial is intended for Web application
+ developers who are supposed to be familiar with the programming
+ language Java and the build tool maven [
+ <a href="#ref3">3</a>
+ ].
+ </p>
+ <h2 id="initialization">2. Initializing a Maven Project</h2>
+ <p>First, a maven project with the groupId org.example.clerezza
+ and the artifactId tutorial1 will be created by executing the
+ following command in a shell:</p>
+ <pre><code>
+ $ mvn archetype:generate --batch-mode \
+ -DarchetypeGroupId=org.apache.maven.archetypes \
+ -DarchetypeArtifactId=maven-archetype-quickstart \
+ -DgroupId=org.example.clerezza \
+ -DartifactId=tutorial1 \
+ -Dversion=1.0-SNAPSHOT \
+ -Dpackage=org.example.clerezza.tutorial1
+ ...
+ ------------------------------------------------------------------------
+ [INFO] BUILD SUCCESSFUL
+ [INFO]
+ ------------------------------------------------------------------------
+ ...
+ </code></pre>
+ <p>A new directory called tutorial1 is created containing a source
+ directory src and a file called pom.xml used by maven to build the
+ project. A program file called App.java is created and placed under
+ the directory src/main/java/org/example/clerezza/tutorial1/. Since we
+ are going to use annotations and generics, we need to configure
+ maven-compiler-plugin in the pom.xml accordingly, i.e., to use javac
+ version 1.5 or higher. In this tutorial we use version 1.6, thus, the
+ modified pom.xml looks as follows:</p>
+ <pre><code>
+ <project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">
+ <modelVersion>4.0.0</modelVersion>
+ <groupId>org.example.clerezza</groupId>
+ <artifactId>tutorial1</artifactId>
+ <packaging>jar</packaging>
+ <version>1.0-SNAPSHOT</version>
+ <name>tutorial1</name>
+ <url>http://maven.apache.org</url>
+ <dependencies>
+ <dependency>
+ <groupId>junit</groupId>
+ <artifactId>junit</artifactId>
+ <version>3.8.1</version>
+ <scope>test</scope>
+ </dependency>
+ </dependencies><strong>
+ <build>
+ <plugins>
+ <plugin>
+ <groupId>org.apache.maven.plugins</groupId>
+ <artifactId>maven-compiler-plugin</artifactId>
+ <configuration>
+ <source>1.6</source>
+ <target>1.6</target>
+ </configuration>
+ </plugin>
+ </plugins>
+ </build></strong>
+ </project>
+ </code></pre>
+
+ <h2 id="functionality">3. Implementing the Functionality</h2>
+ <p>To implement the required functionality, we need a Java class to represent persons and another Java class to manage them. We will modify App.java to implement the second class and write a new file called Person.java to implement the first class. As you can see, both classes are simply POJO. The class App manages an array of Person objects and provides for a method to retrieve a Person object given his ID. For the sake of simplicity, the ID of a person is represented by the respective array index.</p>
+ <p>The content of App.java is as follows:</p>
+ <pre><code>
+ package org.example.clerezza.tutorial1;
+
+ public class App {
+
+ Person[] persons;
+ public App() {
+ persons = new Person[3];
+ persons[0] = new Person("Jane", "Roe");
+ persons[1] = new Person("Richard", "Roe");
+ persons[2] = new Person("John", "Doe");
+ }
+
+ public Person getPerson(int id) {
+ return persons[id];
+ }
+ }
+ </code></pre>
+
+ <p>The class Person is defined in Person.java as follows:</p>
+ <pre><code>
+ package org.example.clerezza.tutorial1;
+
+ public class Person {
+ String firstName, lastName;
+
+ public Person(String firstName, String lastName) {
+ this.firstName = firstName;
+ this.lastName = lastName;
+ }
+
+ public String getFirstName() {
+ return firstName;
+ }
+
+ public String getLastName() {
+ return lastName;
+ }
+ }
+ </code></pre>
+
+ <h2 id="root_resource">4. Making a Class a JAX-RS Root Resource</h2>
+ <p>JAX-RS [<a href="#ref4">4</a>] (a.k.a JSR 311) is the Java API for RESTful Web Services. Since we are going to use JAX-RS in this tutorial, we need to configure this dependency in the pom.xml. The modified pom.xml looks as follows:</p>
+ <pre><code>
+ <project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">
+ ...
+ <dependencies><strong>
+ <dependency>
+ <groupId>javax.ws.rs</groupId>
+ <artifactId>jsr311-api</artifactId>
+ <version>1.0</version>
+ </dependency></strong>
+ ...
+ </dependencies>
+ ...
+ </project>
+ </code></pre>
+
+ <p>The class App is a resource class (in JAX-RS terminology), i.e., a class that implements a Web resource. To denote a resource class, JAX-RS annotations [<a href="#ref5">5</a>] are used, as shown in the class App below. The JAX-RS annotation @Path in this class sets the path of the resource to â/contactâ. The JAX-RS annotation @GET tells that the annotated method, getPerson, is responsible for processing GET requests. This method accepts a parameter, whose value is obtained from the GET request parameter called id. This is defined through the JAX-RS annotation @QueryParam.</p>
+
+ <pre><code>
+ package org.example.clerezza.tutorial1;
+
+ import javax.ws.rs.GET;
+ import javax.ws.rs.Path;
+ import javax.ws.rs.QueryParam;
+
+ @Path("/contact") // sets the path for this service
+ public class App {
+
+ Person[] persons;
+ public App() {
+ persons = new Person[3];
+ persons[0] = new Person("Jane", "Roe");
+ persons[1] = new Person("Richard", "Roe");
+ persons[2] = new Person("John", "Doe");
+ }
+
+ @GET // this method process GET requests
+ public Person getPerson(@QueryParam("id") int id) {
+ return persons[id];
+ }
+ }
+ </code></pre>
+
+ <h2 id="representation">5. Getting the Representation of a Resource</h2>
+ <p>A resource can have multiple representations. For example, a Web page can be represented as html, pdf, plain text, or other representations. The HTTP defines a mechanism known as content negotiation to allow a client (e.g., a Web browser) to specify which representation it would like to get from the server. With JAX-RS we can define writers for various representations. In this tutorial we will add a writer, called PersonWriter, to produce an HTML representation of the resource Person. The content of PersonWriter.java is as follows:</p>
+ <pre><code>
+ package org.example.clerezza.tutorial1;
+
+ import java.io.IOException;
+ import java.io.OutputStream;
+ import java.io.PrintWriter;
+ import java.lang.annotation.Annotation;
+ import java.lang.reflect.Type;
+ import javax.ws.rs.Produces;
+ import javax.ws.rs.WebApplicationException;
+ import javax.ws.rs.core.MediaType;
+ import javax.ws.rs.core.MultivaluedMap;
+ import javax.ws.rs.ext.MessageBodyWriter;
+ import javax.ws.rs.ext.Provider;
+
+ @Provider
+ @Produces("text/html")
+ public class PersonWriter implements MessageBodyWriter<Person> {
+
+ @Override
+ public boolean isWriteable(Class<?> type, Type genericType,
+ Annotation[] annotations, MediaType mediaType) {
+ return Person.class.isAssignableFrom(type);
+ }
+
+ @Override
+ public long getSize(Person t, Class<?> type, Type genericType,
+ Annotation[] annotations, MediaType mediaType) {
+ return -1;
+ }
+
+ @Override
+ public void writeTo(Person t, Class<?> type, Type genericType,
+ Annotation[] annotations, MediaType mediaType,
+ MultivaluedMap<String, Object> httpHeaders,
+ OutputStream entityStream)
+ throws IOException, WebApplicationException {
+ PrintWriter writer = new PrintWriter(entityStream);
+ writer.println("<html>");
+ writer.println("<body>");
+ writer.println("Firstname: "+t.getFirstName());
+ writer.println("<br/>");
+ writer.println("Lastname: "+t.getLastName());
+ writer.println("</body>");
+ writer.println("</html>");
+ writer.flush();
+ }
+ }
+ </code></pre>
+
+ <p>The JAX-RS annotation @Provider tells that the annotated class implements a JAX-RS extension interface. The JAX-RS runtime is extended using application-supplied provider classes. In our case, the class PersonWriter is an entity provider, i.e., a provider that supplies a mapping service between representations and their associated Java types (classes). The PersonWriter maps a Java type to a representation. The JAX-RS annotation @Produces specifies a list of media types that a Java type or a method can produce.</p>
+ <p>To compile the sources, execute:</p>
+ <pre><code>
+ $ mvn compile
+ ...
+ [INFO] [compiler:compile]
+ [INFO] Compiling 3 source files to .../tutorial1/target/classes
+ [INFO] ------------------------------------------------------------------------
+ [INFO] BUILD SUCCESSFUL
+ [INFO] ------------------------------------------------------------------------
+ ...
+ </code></pre>
+
+ <p><strong>Congratulations! You have just written a JAX-RS application.</strong></p>
+ <p>Fig. 1 depicts the class diagram of this simple Web application which comprises 3 classes and 1 interface class. An instance of the class Person (a Person object) represents a person identified by its first name and last name. PersonWriter provides a writeTo method to convert a Person object into a data stream containing the first name and the last name of the person in HTML. It implements the interface MessageBodyWriter defined by the JAX-RS specification.</p>
+ <p><img src="images/tut_1_class_diagram.png" alt="Class Diagram"/><br/><i>Figure 1: Class Diagram of Web Application for Contacts Lookup</i></p>
+ <p>Since we are going to run the application in an OSGi container, let's dive into OSGi world now.</p>
+
+ <h2 id="bundling">6. Configuring Packaging Type and Plugin for Bundling</h2>
+ <p>We need to create a bundle from those classes defined above. To generate a bundle, we need to specify bundle as the packaging type and configure the build to use maven-bundle-plugin in the pom.xml as follows:</p>
+ <pre><code>
+ <project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">
+ ...<strong>
+ <packaging>bundle</packaging> </strong>
+ ...
+ <build>
+ <plugins>
+ ...<strong>
+ <plugin>
+ <groupId>org.apache.felix</groupId>
+ <artifactId>maven-bundle-plugin</artifactId>
+ <extensions>true</extensions>
+ </plugin></strong>
+ ...
+ </plugins>
+ </build>
+ </project>
+ </code></pre>
+
+ <h2 id="declarative_service">7. Using OSGi Declarative Service</h2>
+ <p>We use OSGi Declarative Service (OSGi DS) to wire together services across bundles. This wiring is specified declaratively in XML format, however, we will use maven-scr-plugin to automate the generation of this specification. This requires a plugin configuration in the pom.xml as follows:</p>
+ <pre><code>
+ <project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">
+ ...
+ <build>
+ <plugins>
+ ...<strong>
+ <plugin>
+ <groupId>org.apache.felix</groupId>
+ <artifactId>maven-scr-plugin</artifactId>
+ <executions>
+ <execution>
+ <id>generate-scr-scrdescriptor</id>
+ <goals>
+ <goal>scr</goal>
+ </goals>
+ </execution>
+ </executions>
+ </plugin></strong>
+ ...
+ </plugins>
+ </build>
+ </project>
+ </code></pre>
+
+ <p>We use Triaxrs [<a href="#ref6">6</a>] developed by clerezza.org as the implementation of JAX-RS. It supports both injection of javax.ws.rs.core.Application instances as well as direct injection of Providers and root resources. For a direct injection, a component just needs to expose a service of type java.lang.Object and have the property "javax.ws.rs" set to true. Therefore, the next step is to add OSGi DS annotations to source code to be processed by the maven-scr-plugin.</p>
+ <p>The complete code of App.java looks now as follows:</p>
+ <pre><code>
+ package org.example.clerezza.tutorial1;
+
+ import javax.ws.rs.GET;
+ import javax.ws.rs.Path;
+ import javax.ws.rs.QueryParam;
+
+ /**
+ * Get Persons by id <strong>
+ *
+ * @scr.component
+ * @scr.service interface="java.lang.Object"
+ * @scr.property name="javax.ws.rs" type="Boolean" value="true" </strong>
+ */
+
+ @Path("/contact") // sets the path for this service
+ public class App {
+
+ Person[] persons;
+ public App() {
+ persons = new Person[3];
+ persons[0] = new Person("Jane", "Roe");
+ persons[1] = new Person("Richard", "Roe");
+ persons[2] = new Person("John", "Doe");
+ }
+
+ @GET // this method process GET requests
+ public Person getPerson(@QueryParam("id") int id) {
+ return persons[id];
+ }
+ }
+ </code></pre>
+
+ <p>And the complete code of PersonWriter.java looks as follows:</p>
+ <pre><code>
+ package org.example.clerezza.tutorial1;
+
+ import java.io.IOException;
+ import java.io.OutputStream;
+ import java.io.PrintWriter;
+ import java.lang.annotation.Annotation;
+ import java.lang.reflect.Type;
+ import javax.ws.rs.Produces;
+ import javax.ws.rs.WebApplicationException;
+ import javax.ws.rs.core.MediaType;
+ import javax.ws.rs.core.MultivaluedMap;
+ import javax.ws.rs.ext.MessageBodyWriter;
+ import javax.ws.rs.ext.Provider;
+
+ /**
+ * <strong>
+ * @scr.component
+ * @scr.service interface="java.lang.Object"
+ * @scr.property name="javax.ws.rs" type="Boolean" value="true" </strong>
+ */
+ @Provider
+ @Produces("text/html")
+ public class PersonWriter implements MessageBodyWriter<Person> {
+
+ @Override
+ public boolean isWriteable(Class<?> type, Type genericType,
+ Annotation[] annotations, MediaType mediaType) {
+ return Person.class.isAssignableFrom(type);
+ }
+
+ @Override
+ public long getSize(Person t, Class<?> type, Type genericType,
+ Annotation[] annotations, MediaType mediaType) {
+ return -1;
+ }
+
+ @Override
+ public void writeTo(Person t, Class<?> type, Type genericType,
+ Annotation[] annotations, MediaType mediaType,
+ MultivaluedMap<String, Object> httpHeaders,
+ OutputStream entityStream)
+ throws IOException, WebApplicationException {
+ PrintWriter writer = new PrintWriter(entityStream);
+ writer.println("<html>");
+ writer.println("<body>");
+ writer.println("Firstname: "+t.getFirstName());
+ writer.println("<br/>");
+ writer.println("Lastname: "+t.getLastName());
+ writer.println("</body>");
+ writer.println("</html>");
+ writer.flush();
+ }
+ }
+ </code></pre>
+
+ <p>Based on the @scr annotations, the maven-scr-plugin generates the configuration file serviceComponents.xml and places it in the directory target/scr-plugin-generated/OSGI-INF/ (see the next section). After executing "mvn compile" the file serviceComponents.xml is generated. The content of this file looks as follows:</p>
+ <pre><code>
+ <?xml version="1.0" encoding="UTF-8"?>
+ <components xmlns:scr="http://www.osgi.org/xmlns/scr/v1.0.0">
+ <scr:component enabled="true" name="org.example.clerezza.tutorial1.App">
+ <scr:implementation class="org.example.clerezza.tutorial1.App"/>
+ <scr:service servicefactory="false">
+ <scr:provide interface="java.lang.Object"/>
+ </scr:service>
+ <scr:property name="javax.ws.rs" type="Boolean" value="true"/>
+ <scr:property name="service.pid" value="org.example.clerezza.tutorial1.App"/>
+ </scr:component>
+ <scr:component enabled="true" name="org.example.clerezza.tutorial1.PersonWriter">
+ <scr:implementation class="org.example.clerezza.tutorial1.PersonWriter"/>
+ <scr:service servicefactory="false">
+ <scr:provide interface="java.lang.Object"/>
+ </scr:service>
+ <scr:property name="javax.ws.rs" type="Boolean" value="true"/>
+ <scr:property name="service.pid" value="org.example.clerezza.tutorial1.PersonWriter"/>
+ </scr:component>
+ </components>
+ </code></pre>
+
+ <p>The file serviceComponents.xml specifies that there are two OSGi components called org.example.clerezza.tutorial1.App and org.example.clerezza.tutorial1.PersonWriter which are to be enabled. A component needs to be enabled before its configuration can be activated. If you are interested in the detail description of a component life cycle, you can obtain this information from the OSGi Service Platform Service Compendium [<a href="#ref7">7</a>] Section 112.5. The serviceComponents.xml also specifies the class that is to be loaded when a component is activated. Based on this component description, the OSGi runtime can determine and invoke service instances referred to by Triaxrs.</p>
+
+ <h2 id="build">8. Building Tutorial1 Bundle</h2>
+ <p>Now we can build the tutorial1 bundle with the following command:</p>
+ <pre><code>
+ $ mvn clean install
+ ...
+ [INFO] [clean:clean]
+ [INFO] [resources:resources]
+ ...
+ [INFO] [compiler:compile]
+ [INFO] Compiling 3 source files to .../tutorial1/target/classes
+ [INFO] [scr:scr {execution: generate-scr-scrdescriptor}]
+ [INFO] Generating 4 MetaType Descriptors to .../tutorial1/target/scr-plugin-generated/OSGI-INF/metatype/metatype.xml
+ [INFO] Writing abstract service descriptor .../tutorial1/target/scr-plugin-generated/OSGI-INF/scr-plugin/scrinfo.xml with 2 entries.
+ [INFO] Generating 2 Service Component Descriptors to .../tutorial1/target/scr-plugin-generated/OSGI-INF/serviceComponents.xml
+ [INFO] [resources:testResources]
+ [INFO] Using default encoding to copy filtered resources.
+ [INFO] [compiler:testCompile]
+ [INFO] Compiling 1 source file to .../tutorial1/target/test-classes
+ [INFO] [surefire:test]
+ ...
+ [INFO] [bundle:bundle]
+ [INFO] [install:install]
+ [INFO] Installing .../tutorial1/target/tutorial1-1.0-SNAPSHOT.jar to .../.m2/repository/org/example/clerezza/tutorial1/1.0-SNAPSHOT/tutorial1-1.0-SNAPSHOT.jar
+ [INFO] [bundle:install]
+ [INFO] Parsing file:/home/origami/.m2/repository/repository.xml
+ [INFO] Installing org/example/clerezza/tutorial1/1.0-SNAPSHOT/tutorial1-1.0-SNAPSHOT.jar
+ [INFO] Writing OBR metadata
+ [INFO] ------------------------------------------------------------------------
+ [INFO] BUILD SUCCESSFUL
+ [INFO] ------------------------------------------------------------------------
+ ...
+ </code></pre>
+
+ <p>If there is no error occurred during the build, maven will generate the package tutorial1-1.0-SNAPSHOT.jar, place it in the directory target and install it into the local repository. Besides serviceComponents.xml described above, the maven-scr-plugin also generates metatype.xml and scrinfo.xml within the OSGI-INF directory. The metatype.xml specifies the type of data that a service can use as arguments (cf. Section 105 of [<a href="#ref7">7</a>]), whereas the scrinfo.xml contains abstract service description. The maven-bundle-plugin generates the file MANIFEST.MF and places it in the directory classes/META-INF/. This file describes the generated bundle JAR as shown below. It specifies amongst others the packages that are to be exported and imported by the bundle, the location and the name of the component configuration file serviceComponents.xml. The information about the location and name of the component configuration file comes from the maven-scr-plugin.</p>
+
+ <pre><code>
+ Manifest-Version: 1.0
+ Export-Package: org.example.clerezza.tutorial1;uses:="javax.ws.rs,javax
+ .ws.rs.ext,javax.ws.rs.core"
+ Service-Component: OSGI-INF/serviceComponents.xml
+ Built-By: hasan
+ Tool: Bnd-0.0.255
+ Bundle-Name: Tutorial 1
+ Created-By: Apache Maven Bundle Plugin
+ Bundle-Version: 1.0.0.SNAPSHOT
+ Build-Jdk: 1.6.0_07
+ Bnd-LastModified: 1223461032518
+ Bundle-ManifestVersion: 2
+ Import-Package: javax.ws.rs,javax.ws.rs.core,javax.ws.rs.ext,org.examp
+ le.clerezza.tutorial1
+ Bundle-SymbolicName: org.example.clerezza.tutorial1
+ </code></pre>
+
+ <h2 id="deploy">9. Deploying and Starting the Bundle in an OSGi Container</h2>
+ <p>We will deploy tutorial1 bundle generated by maven and all its required bundles in Apache Felix, which is an OSGi container. Table 1 lists all bundles needed in this tutorial in addition to bundles that are already started by Apache Felix.</p>
+ <p><i>Table 1: Bundles Needed in Tutorial 1</i></p>
+ <table border="1" cellpadding="4">
+ <tr>
+ <th>Bundle Name</th>
+ <th>Bundle Symbolic Name</th>
+ <th>Required By</th>
+ </tr>
+ <tr>
+ <td>Servlet Specification 2.5 API</td>
+ <td>org.mortbay.jetty.servlet-api-2.5</td>
+ <td>Jetty Utilities</td>
+ </tr>
+ <tr>
+ <td>Jetty Utilities</td>
+ <td>org.mortbay.jetty.util</td>
+ <td>Jetty Server</td>
+ </tr>
+ <tr>
+ <td>Jetty Server</td>
+ <td>org.mortbay.jetty.server</td>
+ <td>WRHAPI Jetty</td>
+ </tr>
+ <tr>
+ <td>Apache Commons Logging Plug-in</td>
+ <td>org.apache.commons.logging</td>
+ <td>WRHAPI Jetty</td>
+ </tr>
+ <tr>
+ <td>WRHAPI</td>
+ <td>org.wymiwyg.wrhapi</td>
+ <td>WRHAPI Jetty, Clerezza - Triaxrs</td>
+ </tr>
+ <tr>
+ <td>WRHAPI Jetty</td>
+ <td>org.wymiwyg.wrhapi-jetty</td>
+ <td>-</td>
+ </tr>
+ <tr>
+ <td>jsr311-api</td>
+ <td>javax.ws.rs.jsr311-api</td>
+ <td>Clerezza - Triaxrs, Tutorial 1</td>
+ </tr>
+ <tr>
+ <td>Sling - OSGi LogService Implementation</td>
+ <td>org.apache.sling.commons.log</td>
+ <td>Clerezza - Triaxrs</td>
+ </tr>
+ <tr>
+ <td>Clerezza - JAXRS Extensions</td>
+ <td>org.clerezza.jaxrs.extensions</td>
+ <td>Clerezza - Triaxrs</td>
+ </tr>
+ <tr>
+ <td>Clerezza - Triaxrs</td>
+ <td>org.clerezza.triaxrs</td>
+ <td>-</td>
+ </tr>
+ <tr>
+ <td>Tutorial 1</td>
+ <td>org.example.clerezza.tutorial1</td>
+ <td>-</td>
+ </tr>
+ <tr>
+ <td>Apache Felix Declarative Services</td>
+ <td>org.apache.felix.scr</td>
+ <td>-</td>
+ </tr>
+ </table>
+ <p><br/></p>
+ <p>Apache Felix can be downloaded from <a href="http://felix.apache.org/site/downloads.cgi">http://felix.apache.org/site/downloads.cgi</a>. The current version of Felix at the time of writing this tutorial is version 1.6.0. To install, you just need to untar the downloaded package felix-1.6.0.tar.gz:</p>
+ <pre><code>
+ $ tar xzvf felix-1.6.0.tar.gz
+ </code></pre>
+
+ <p>To run Felix, change the working directory to felix-1.6.0 and then execute the program felix.jar in the directory bin. You will be asked for a profile name which identifies a set of bundles to be installed or that was previously installed and associated with this profile name. Felix creates a directory for each profile and places it in the directory ~/.felix by default. In this tutorial we use tutorial_1 as the profile name. After you have entered the profile name, the Felix shell is started and the prompt â->â is shown.</p>
+ <pre><code>
+ $ cd felix-1.6.0
+ $ java -jar bin/felix.jar
+
+ Welcome to Felix.
+ =================
+
+ ->
+ </code></pre>
+
+ <p>You can enter commands after the prompt of the Felix shell. Read the Apache Felix Usage Documentation [<a href="#ref8">8</a>] for a list of commands and their descriptions. Those bundles listed above can be installed and started as shown below. Note that not all bundles need to be started, e.g., API bundles such as javax.ws.rs need only be installed.</p>
+ <pre><code>
+ -> start http://mirrors.ibiblio.org/pub/mirrors/maven2/org/apache/felix/org.apache.felix.scr/1.0.6/org.apache.felix.scr-1.0.6.jar
+ -> install http://repo1.maven.org/maven2/org/mortbay/jetty/servlet-api-2.5/6.1.11/servlet-api-2.5-6.1.11.jar
+ -> install http://repo1.maven.org/maven2/org/mortbay/jetty/jetty-util/6.1.11/jetty-util-6.1.11.jar
+ -> install http://repo1.maven.org/maven2/org/mortbay/jetty/jetty/6.1.11/jetty-6.1.11.jar
+ -> start http://mirror.switch.ch/mirror/apache/dist/sling/org.apache.sling.commons.log-2.0.6.jar
+ -> start http://wymiwyg.berlios.de/maven2/org/wymiwyg/wrhapi/0.6/wrhapi-0.6.jar
+ -> start http://wymiwyg.berlios.de/maven2/org/wymiwyg/wrhapi-jetty/0.6/wrhapi-jetty-0.6.jar
+ -> install http://repo1.maven.org/maven2/javax/ws/rs/jsr311-api/1.0/jsr311-api-1.0.jar
+ -> start http://repo.trialox.org/release/org/clerezza/org.clerezza.jaxrs.extensions/0.1/org.clerezza.jaxrs.extensions-0.1.jar
+ -> start http://repo.trialox.org/release/org/clerezza/org.clerezza.triaxrs/0.6/org.clerezza.triaxrs-0.6.jar
+ -> start file:///home/.../tutorial1/target/tutorial1-1.0-SNAPSHOT.jar
+ </code></pre>
+
+ <h2 id="service_access">10. Accessing the Web Service</h2>
+ <p>Now, open a Web Browser window and access the service through the URL: http://localhost:8080/contact?id=2</p>
+ <p>As a response from the server, your Web Browser should show the following text in the window:</p>
+ <pre><code>
+ Firstname: John
+ Lastname: Doe
+ </code></pre>
+ <p>Surely you have noticed the use of the port number 8080 in the URL. This is due to the fact that the Activator bundle configures the Jetty Web server to listen on this port number.</p>
+
+ <h2 id="references">11. References</h2>
+ <p id="ref1">[1] R.T. Fielding: Architectural Styles and the Design of Network-based Software Architectures; CHAPTER 5 Representational State Transfer (REST), 2000, <a href="http://www.ics.uci.edu/~fielding/pubs/dissertation/rest_arch_style.htm">http://www.ics.uci.edu/~fielding/pubs/dissertation/rest_arch_style.htm</a></p>
+ <p id="ref2">[2] OSGi, <a href="http://www.osgi.org/Main/HomePage">http://www.osgi.org/Main/HomePage</a></p>
+ <p id="ref3">[3] Maven, <a href="http://maven.apache.org/">http://maven.apache.org/</a></p>
+ <p id="ref4">[4] JAX-RS: The Java API for RESTful Web Services, <a href="http://jcp.org/en/jsr/detail?id=311">http://jcp.org/en/jsr/detail?id=311</a></p>
+ <p id="ref5">[5] JAX-RS Annotations, <a href="https://jsr311.dev.java.net/nonav/javadoc/javax/ws/rs/package-summary.html">https://jsr311.dev.java.net/nonav/javadoc/javax/ws/rs/package-summary.html</a></p>
+ <p id="ref6">[6] Triaxrs, <a href="http://trialox.org/projects/org.clerezza.triaxrs.parent/org.clerezza.triaxrs/index.html">http://trialox.org/projects/org.clerezza.triaxrs.parent/org.clerezza.triaxrs/index.html</a></p>
+ <p id="ref7">[7] The OSGi Alliance: OSGi Service Platform Service Compendium; Release 4, Version 4.1, April 2007</p>
+ <p id="ref8">[8] Apache Felix: Apache Felix Usage Documentation; <a href="http://felix.apache.org/site/apache-felix-usage-documentation.html">http://felix.apache.org/site/apache-felix-usage-documentation.html</a></p>
+
+ <p><i>That's all folks for this time! <br/><!--You can send your feedback to: --></i></p>
</body>
</html>
-