forked from javaee/jersey-1.x
-
Notifications
You must be signed in to change notification settings - Fork 0
/
getting-started.html
201 lines (192 loc) · 11.2 KB
/
getting-started.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<HTML>
<HEAD>
<!--
DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
Copyright (c) 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.
-->
<META HTTP-EQUIV="CONTENT-TYPE" CONTENT="text/html; charset=utf-8">
<TITLE>Getting Started</TITLE>
<META NAME="GENERATOR" CONTENT="OpenOffice.org 3.0 Beta (Unix)">
<META NAME="CREATED" CONTENT="0;0">
<META NAME="CHANGED" CONTENT="20081008;15594200">
<META NAME="Info 1" CONTENT="">
<META NAME="Info 2" CONTENT="">
<META NAME="Info 3" CONTENT="">
<META NAME="Info 4" CONTENT="">
</HEAD>
<BODY LANG="en-US" DIR="LTR">
<H1>Getting Started</H1>
<P>This document will present how to get started with Jersey using
the embedded Grizzly server. The last section of this document
presents a reference to equivalent functionality for getting started
with a Web application.</P>
<P>First, it is necessary to depend on the correct Jersey artifacts
as described in the <A HREF="dependencies.html">dependencies</A>
document.</P>
<P>Maven developers require a dependency on the <A HREF="http://download.java.net/maven/2/com/sun/jersey/jersey-server/1.1.3-ea-SNAPSHOT/jersey-server-1.1.3-ea-SNAPSHOT.pom">jersey-server</A>
module, the <A HREF="http://download.java.net/maven/2/com/sun/grizzly/grizzly-servlet-webserver/1.9.8/grizzly-servlet-webserver-1.9.8.pom">grizzly-servlet-webserver</A>
module and optionally for WADL support if using Java SE 5 the
<A HREF="http://download.java.net/maven/1/com.sun.xml.bind/poms/jaxb-impl-2.1.pom">jaxb-impl</A>
module. The following dependencies need to be added to the pom:</P>
<PRE STYLE="margin-left: 0.79in"><dependency>
<groupId>com.sun.jersey</groupId>
<artifactId>jersey-server</artifactId>
<version>1.1.3-ea-SNAPSHOT</version>
</dependency><dependency>
<groupId>com.sun.grizzly</groupId>
<artifactId>grizzly-servlet-webserver</artifactId>
<version>1.9.8</version>
</dependency></PRE><P>
And the following repositories need to be added to the pom:</P>
<PRE STYLE="margin-left: 0.79in"><repository>
<id>maven2-repository.dev.java.net</id>
<name>Java.net Repository for Maven</name>
<url>http://download.java.net/maven/2/</url>
<layout>default</layout>
</repository>
<repository>
<id>maven-repository.dev.java.net</id>
<name>Java.net Maven 1 Repository (legacy)</name>
<url>http://download.java.net/maven/1</url>
<layout>legacy</layout>
</repository></PRE><P>
Non-maven developers require:</P>
<BLOCKQUOTE><A HREF="http://download.java.net/maven/2/com/sun/grizzly/grizzly-servlet-webserver/1.9.8/grizzly-servlet-webserver-1.9.8.jar">grizzly-servlet-webserver.jar</A>,
<A HREF="http://download.java.net/maven/2/com/sun/jersey/jersey-server/1.1.3-ea-SNAPSHOT/jersey-server-1.1.3-ea-SNAPSHOT.jar">jersey-server.jar</A>,
<A HREF="http://download.java.net/maven/2/com/sun/jersey/jersey-core/1.1.3-ea-SNAPSHOT/jersey-core-1.1.3-ea-SNAPSHOT.jar">jersey-core.jar</A>,
<A HREF="http://download.java.net/maven/2/javax/ws/rs/jsr311-api/1.0/jsr311-api-1.0.jar">jsr311-api.jar</A>,
<A HREF="http://repo1.maven.org/maven2/asm/asm/3.1/asm-3.1.jar">asm.jar</A></BLOCKQUOTE>
<P>and optionally for WADL support if using Java SE 5:</P>
<BLOCKQUOTE><A HREF="http://download.java.net/maven/1/com.sun.xml.bind/jars/jaxb-impl-2.1.jar">jaxb-impl.jar</A>,
<A HREF="http://download.java.net/maven/1/javax.xml.bind/jars/jaxb-api-2.1.jar">jaxb-api.jar</A>,
<A HREF="http://download.java.net/maven/1/javax.activation/jars/activation-1.1.jar">activation.jar</A>,
<A HREF="http://download.java.net/maven/1/javax.xml.stream/jars/stax-api-1.0-2.jar">stax-api.jar</A></BLOCKQUOTE>
<BLOCKQUOTE STYLE="margin-left: 0in; margin-right: 0in">For Ant
developers the <A HREF="http://maven.apache.org/ant-tasks.html">Ant
Tasks for Maven</A> may be used to add the following to the ant
document such that the dependencies do not need to be downloaded
explicitly:</BLOCKQUOTE>
<PRE STYLE="margin-left: 0.79in"><artifact:dependencies pathId="dependency.classpath">
<dependency groupId="com.sun.jersey"
artifactId="jersey-server"
version="1.1.3-ea-SNAPSHOT"/>
<dependency groupId="com.sun.grizzly"
artifactId="grizzly-servlet-webserver"
version="1.8.6.4"/>
<artifact:remoteRepository id="maven2-repository.dev.java.net"
url="http://download.java.net/maven/2/" />
<artifact:remoteRepository id="maven-repository.dev.java.net"
url="http://download.java.net/maven/1"
layout="legacy" />
</artifact:dependencies></PRE><BLOCKQUOTE STYLE="margin-left: 0in; margin-right: 0in">
The path id “dependency.classpath” may then be referenced as the
classpath to be used for compiling or executing.</BLOCKQUOTE>
<P>Second, create a new project (using your favourite IDE or just
ant/maven) and add the dependences. (For those who want to skip the
creation of their own project take a look at the last <A HREF="#created">section</A>
of this document.)</P>
<H1>Creating a root resource</H1>
<P>Create the following Java class in your project:</P>
<PRE> 1 // The Java class will be hosted at the URI path "/helloworld"
2 @Path("/helloworld")
3 public class HelloWorldResource {
4
5 // The Java method will process HTTP GET requests
6 @GET
7 // The Java method will produce content identified by the MIME Media
8 // type "text/plain"
9 @Produces("text/plain")
10 public String getClichedMessage() {
11 // Return some cliched textual content
12 return "Hello World";
13 }
14 }</PRE><P>
The <CODE>HelloWorldResource</CODE> class is a very simple Web
resource. The URI path of the resource is "/helloworld"
(line 2), it supports the HTTP GET method (line 6) and produces
cliched textual content (line 12) of the MIME media type "text/plain"
(line 9).</P>
<P>Notice the use of Java annotations to declare the URI path, the
HTTP method and the media type. This is a key feature of JSR 311.</P>
<H1>Deploying the root resource</H1>
<P>The root resource will be deployed using the Grizzly Web
container.</P>
<P>Create the following Java class in your project:</P>
<PRE> 1 public class Main {
2
3 public static void main(String[] args) throws IOException {
4
5 final String baseUri = "http://localhost:9998/";
6 final Map<String, String> initParams = new HashMap<String, String>();
7
8 initParams.put("com.sun.jersey.config.property.packages",
9 "com.sun.jersey.samples.helloworld.resources");
10
11 System.out.println("Starting grizzly...");
12 SelectorThread threadSelector = GrizzlyWebContainerFactory.create(
13 baseUri, initParams);
14 System.out.println(String.format(
15 "Jersey app started with WADL available at %sapplication.wadl\n” +
16 “Try out %shelloworld\nHit enter to stop it...", baseUri, baseUri));
17 System.in.read();
18 threadSelector.stopEndpoint();
19 System.exit(0);
20 }
21 }</PRE><P>
The <CODE>Main</CODE> class deploys the <CODE>HelloWorldResource</CODE>
using the Grizzly Web container.</P>
<P>Lines 8 to 9 creates an initialization parameter that informs the
Jersey runtime where to search for root resource classes to be
deployed. In this case it assumes the root resource class in the
package <FONT FACE="Courier New, monospace">com.sun.jersey.samples.helloworld.resources</FONT>
(or in a sub-package of).</P>
<P>Lines 12 to 13 deploys the root resource to the base URI
"<A HREF="http://localhost:9998/">http://localhost:9998/</A>"
and returns a Grizzly SelectorThread. The complete URI of the Hello
World root resource is "<A HREF="http://localhost:9998/helloworld">http://localhost:9998/helloworld</A>".</P>
<P>Notice that no deployment descriptors were needed and the root
resource was setup in a few statements of Java code.</P>
<H1>Testing the root resource</H1>
<P>Goto the URI <A HREF="http://localhost:9998/helloworld">http://localhost:9998/helloworld</A>
in your favourite browser.</P>
<P>Or, from the command line use <CODE>curl:</CODE></P>
<PRE STYLE="margin-bottom: 0.2in"><CODE> > curl http://localhost:9998/helloworld</CODE></PRE><H1>
<A NAME="created"></A>Here's one I created earlier</H1>
<P>The example code presented above is shipped as the <A HREF="http://download.java.net/maven/2/com/sun/jersey/samples/helloworld/1.1.3-ea-SNAPSHOT/helloworld-1.1.3-ea-SNAPSHOT-project.zip">HelloWorld</A>
sample in the Java.Net maven repository.</P>
<P>For developers wishing to get started by deploying a Web
application an equivalent sample, as a Web application, is shipped as
the <A HREF="http://download.java.net/maven/2/com/sun/jersey/samples/helloworld-webapp/1.1.3-ea-SNAPSHOT/helloworld-webapp-1.1.3-ea-SNAPSHOT-project.zip">HelloWorld-WebApp</A>
sample.</P>
</BODY>
</HTML>