JSR 224 INTRODUCTION

farrierlimpingInternet και Εφαρμογές Web

31 Οκτ 2013 (πριν από 3 χρόνια και 11 μήνες)

99 εμφανίσεις






NetbeansColors.org

JSR 224
INTRODUCTION

JAX
-
WS 2.0 Standardized
Web Service
s Stack
W
ith Metro,

A Practical Guide

For
Java
Beginners

Jonathan Lermitage

2012
-
11
-
07


C
ontent of this document

1


Content of this document

The goal of is document is to provide keys to beginners in order to be able to develop and deploy a
simple
Web Service
, and create a client to consume it.

You need basic Java programming knowledge

only
: you know what are a Java pr
ogram, a class, a method

and a package
.

I
t

includes an introduction to the following software and frameworks:

-

Metro 2.2 as the
Web Service
s framework.

-

Oracle
GlassFish

3.1.2.2 as the Java EE server
.

-

Oracle
NetBeans 7.2.1 as the Java development environment
, with a Java6 JDK (JDK6).

You have already installed:

-

A Java6 (or Java7) JDK. If not, download a “
Java SE
” JDK package from
http://www.oracle.com/technetwork/java/javase/do
wnloads/index.html

and install it.

-

An Internet browser (like Internet Explorer, Opera, Firefox, Chrome
, Safari
…).

Examples have been developed and tested with Microsoft Windows 7 SP1 x64. They are designed to
work with every
32bits and 64bits
operating sys
tem that supports Java6, like Windows XP or UNIX
/BSD

systems (Linux, Solaris,
MacOS,
etc.). You can use a Java7 JDK too.



Content of this document

2


Table of Contents

Content of this document

................................
................................
................................
....................

1

1
-

What are Web Services, JSR 224 and Metro

................................
................................
.....................

3

Web Services

................................
................................
................................
................................
..

3

JSR 224

................................
................................
................................
................................
...........

3

Metro

................................
................................
................................
................................
.............

3

2
-

Prepare GlassFish 3.1
................................
................................
................................
......................

4

Download GlassFish
................................
................................
................................
.........................

4

Start and
configure GlassFish

................................
................................
................................
...........

4

Change the administrator password and/or username

................................
................................
...

4

Enable the secure administration interface (HTTPS instead of HTTP)
................................
...............

5

3
-

Prepare NetBeans

................................
................................
................................
...........................

6

Install NetBeans

................................
................................
................................
..............................

6

Register the GlassFish server into NetBeans

................................
................................
......................

6

4
-

Develop a
Web Service

................................
................................
................................
...................

7

Create a Java Web project

................................
................................
................................
...............

7

Develop the Web Service

................................
................................
................................
.................

7

5
-

Deploy a Web Service

................................
................................
................................
.....................

8

Depl
oy via the Web administration interface

................................
................................
....................

8

Deploy via NetBeans
................................
................................
................................
........................

9

6


The bundled Web Service tester

................................
................................
................................
.....

9

7
-

Develop a Web Service client

................................
................................
................................
........

10

Create a main class

................................
................................
................................
........................

10

Retrieve the WSDL file of the Web Service

................................
................................
......................

10

Use the NetBeans/Metro assistant to generate a Web Service client

................................
................

11

A simple Web Service client
................................
................................
................................
........

11

A more configurable Web Service client

................................
................................
......................

12


1
-

What are Web Services, JSR 224 and Metro

3


1
-

What are
Web
Service
s
,
JSR 224

and Metro

Web Service
s

There are many ways to make two programs to communicate over the network (e.g. the Internet): you
can establish a socket connection
and code every communication manually. You’ll have to prepare a very
neat
communication protocol if you want your copartner to understand you and make it work. So, you
have already understood this approach is dangerous and too complicated.

Another solution: a

Web Service

is a software component that communicates with other softw
are by
using a standardized messages format. These messages are based on XML and formatted using SOAP
(Simple Object Access Protocol)
.
They are described by WSDL (
Web Service

Description Language) files,
so it is easy to discover what a
Web Service

can off
er.
You don’t have to reinvent a protocol each time.


NB: The
Web Service

is the
server side
, and the client that will consume the
Web Service

is the
client side
.

The advantage of a
Web Service

is evident: XML messages are easy to handle
, they are standard
ized

and

they are cross
-
platform
. You can create a
Web Service

based on any programming language that has
some
Web Service
s toolkits (like Java, PHP, C#), and consume it with any language too. As an example,
you can develop the server side with Java, and t
he client side with PHP.

Don’t worry about the SOAP and
WSDL formats: existing toolkits handle them, so you’ll only have to use some
features

to make them
work.

For Java programmers, you can see a
Web Service

as a simple class with methods. When you consum
e a
Web Service
, you call these methods rem
otely and receive their result.
That is not more complicated.

Many companies use
Web Service
s, such as Google,
Facebook,
Twitter, PayPal, etc. Most of them
provide toolkits and code examples in order to handle the
ir services easily

with many programming
languages
. That
is probably
why
Web Service
s are the best

and easiest

way to establish a communication
between two software components.

JSR 224

A JSR (Java Specification Request) is

a mechanism that allow
s

organizat
ions and companies

to develop
standards specifications for the Java ecosystem
.

Some of the most famous JSR are JSR 127 and JSR 152:
they offered us JSF (
J
ava Server Faces) and JSP (Java Server Pages).

JSR 224 has simply invented the JAX
-
WS 2.0 specification (Java API for XML
-
based
Web Service
s 2.0). For
your information, JAX
-
WS 1.0 doesn’t really exist: its ancestor is called JAX
-
RPC (Java API for XML
-
based
Remote Procedure Calling).

Metro

Since JSR 224

is a specification only, we need a reference implementation: the Metro project. Metro is a
part of the
GlassFish

Java EE server project, and can be used outside of the server to develop
Web
Service
s and clients. You’ll find many JSR 224 compliant implemen
tations like Apache CXF

and Axis2.

2
-

Prepare GlassFish 3.1

4


Metro is already bundled with many modern Java EE servers, so you won’t have to download it to
develop and install
Web Service
s.
You may not have to download Metro for client development too
because it is already bundled
with J
ava
6 and J
ava
7. You’ll need a separate download if you use J
ava
5
only. Meanwhile, since J
ava
5 is an outdated version of the Java
platform
, we will focus on JDK6

only

(
please note that
every code example shown in this paper will work with JDK7 wit
h no modification).

2

-

Prepare

GlassFish

3.1

Download
GlassFish

Every Java EE server bundles a JSR 224 implementation library. We will use
GlassFish

3.1.2.2

Full Profile:
it comes with Metro 2.2.1
-
1.

Please note that
GlassFish

exists in two versions:

-

The
“Full Profile”, that is a full Java EE compliant server (it supports all of the Java EE features)
.

-

The “
Web

Profile”, that is a lightweight Java server (like Apache Tomcat



a simple Servlet
container
, it supports

some Java EE features only : you’ll have t
o install a JSR
224
implementation by yourself
)
.

Download
GlassFish

3.1.2.2 from
http://
GlassFish
.java.net/downloads/3.1.2.2
-
final.html
. We will use the
default ZIP version:
http://download.java.net/
GlassFish
/3.1.2.2/release/
GlassFish
-
3.1.2.2.zip
. It comes
with an English

language

interface and contains binaries for Microsoft Windows and
UNI
X

operating
systems

(Linux, MacOS and AIX)
.

Unzip the
GlassFish

archive.

Start and configure
GlassFish

-

Add your JDK

bin


directory (e.g. “
C:
\
Java
\
jdk1.6.0
\
bin”) to the
“PATH” environment v
ariable, in
order to run Java programs and
GlassFish

scripts easily

from the command line.


-

Add your JDK installation path (e.g. “
C:
\
Java
\
jdk1.6.0
”) to the
“JAVA_HOME”

environment
variable
.

-

Add your
GlassFish

ins
tallation path to the

GLASSFISH
_HOME”
environment
variable.

You can now
go to the
GlassFish

“bin” directory and start a command line interpreter (Microsoft

Windows CMD or UNIX shell).

To start the
GlassFish

server, run “
asadmin

start
-
domain domain1
”.

Once
GlassFish

has started, launch your favorite Internet browser and go to “
localhost:4848
”. You may
be automatically logged on. Now, the first
two
things to do are to:

C
hange the administrator password and/or username

-

In the left side panel, go to: “Configuration
s
”, “server
-
config”, “Security”, “Realms”, “admin
-
realm” : use the “Manage Users”
button :

2
-

Prepare GlassFish 3.1

5



-

Use the “New” button and create a new administrator user and validate with the “OK” button.

-

Log off thanks the “Logout” button and log on with your new user.

-

Return to the user accounts management page (the “Manage Users” button previously seen)

and
delete the default administrator user in order to keep the new one only.

Enable the secure administration interface (HTTPS instead of HTTP)

-

GlassFish

running
,

go to its “bin” folder and launch this command line instruction:

asadmin

enable
-
secure
-
admi
n
”. It will make the administration
Web

interface to run over
HTTPS instead of HTTP.

-

You can now shut down
GlassFish

with the following instruction: “
asadmin

stop
-
domain
domain1
”.

-

Start
GlassFish

again:

it is now well configured and ready

to run future app
lications.

3
-

Prepare NetBeans

6


3
-

Prepare

NetBeans

Install NetBeans

Download and install the “All” or “Java EE” package of NetBeans from
http://netbeans.org/downloads/
.
The latest version of NetBeans is 7.2.1. The “Java EE” package contains tools to work with classic Java
desktop applications (Java SE: Java
S
tandard Edition) and applications for Java
Web

servers and Business
technologies (Java EE: Java Enterprise Editio
n). The “All” package contains Java SE and Java EE tools, plus
many others like C++ and PHP support.

Start NetBeans. From the main menu, go to “Tools”, “Plugins”, the “Installed” tab, activ
at
e the “Show
Details” checkbox, select all modules (Ctrl+A) and us
e the “Activate” button. All NetBeans functionalities
are now activated.

NB:
B
y default, NetBeans activates modules (functionalities) on demand only. For practice reasons, we
have chosen to activate them definitively.

NetBeans is now installed and ready fo
r Java EE (and
Web Service
s) development.

Register the
GlassFish

server into NetBeans

Into NetBeans, go to the “Services” tab, expand the “Servers”
node,
do

a right
-
click and choose
the
“Add Server…” option:

-

Choose “
GlassFish

Server 3+” and, if need, customize
its name (e.g.

GlassFish

3.1.2.2 Samples Server

).

-

Select the installation location of
GlassFish

(where you
have unzipped it).

-

Select “Register Local Domain” and “domain1”, and
finish.

The
GlassFish

server is now regist
ered into NetBeans. You can
examine its state from the “Services” tab. To start and stop
GlassFish, you have the choice
: use the regular “asadmin”
command line tool, or use NetBeans: right
-
click on the
registered server, and choose “Start” or “Stop”.

Tip:
P
lease avoid starting
GlassFish

from the command line and stopping

it

from NetBeans (and vice
versa). If you start
GlassFish

from a specified way, stop it from the same.

NB: Registering a server into NetBeans can be useful to start and stop it, and deploy or undeploy
Web

applications.

You won’t have to use the
Web

administration interface.

You can debug
Web

applications
too, view logs,
etc
. Many servers can be registered i
nto NetBeans: Oracle
GlassFish
, Apache Tomcat,
JBoss, and Oracle
Web
Logic. Many others can be supported with additional plugins (like IBM
Web
Sphere
and Apache Geronimo).

4
-

Develop a Web Service

7


4

-

Develop a
Web Service

Create a Java
Web

project

-

Launch the New Project assistant:
“File”, “New Project” (or Ctrl+Shift+N).

-

Select the “Java
Web
” category and the “
Web

Application” project type. Validate.

-

Type a project name
(e.g. “jaxws2
-
service”)
and validate.

-

In the servers list, select the registered
GlassFish

server. Select the “Jav
a EE 6
Web
” option for
the “Java EE Version” field. Validate.

-

Don’t select any framework (Spring, Struts, etc.). Simply validate with the “Finish” button.

Develop the
Web Service

Show the “Project” view and create a package and a class into the “Source Pac
kage” node (“File”, “New
File”, “Java”, “Java Class”). In our example, we will create the “
WSDemo
” class into the

fr.tikione.jaxws2.service
” package
:


Now, type the following content into the class Java code
:

package fr.tikione.jaxws2.service;


import ja
vax.jws.WebMethod;

import javax.jws.WebParam;

import javax.jws.WebService;


@WebService(serviceName = "WSDemo")

public class WSDemo {



@WebMethod(operationName = "sum")


public int sum(@WebParam(name = "numA") int numA,



@WebParam(
name = "numB") int numB) {


return numA + numB;


}

}

NB: You can find the project
s

source code at:
http://netbeanscolors.org/files/jsr224/sample.zip
.


5
-

Deploy a Web Service

8


Now, let’s examine this Java
code:

-

Instructions that begin with the “@” character are special instructions called “annotations”. They
are designed to generate or modify you
r

code during compilation. We will use them to transform
a simple class into a
Web Service
.

-

The “WSDemo” class wi
ll be our
Web Service
. Check the “
@
Web
Service
” annotation before the
class declaration. This annotation takes a parameter: the name of the
Web Service
.

Keep it
simple: use the class name.

NB: Without this annotation, it would be a simple class, without an
y
Web Service
s capabilities.

-

The “sum” method will be a method of the
Web Service
.

Check the “
@
Web
Method
” annotation.
Like the previous annotation, this one take
s

a parameter too: the method’s name.

NB: A
Web Service

can have multiple methods.

Use this ann
otation for every method you want to
publish. Other methods won’t be published as
Web Service
s methods.

-

The “sum” method has two arguments: two integers. Since the method is a part of the
Web
Service
, we have annotations for its arguments too. Check the “
@
Web
Param
” annotations. As
usual, keep it simple and simply repeat the arguments names.

-

The three imports are here for the th
r
ee annotations: “
Web
Service”, “
Web
Method” and

Web
Param”.

You have probably understood the goal of this
Web Service
: it is called “
WSDemo” and it has one
published method. This method computes the sum of two integers and returns this value.

You can now build the project: F11 of right
-
click on the project, and choose “Build”. A “.war” file will be
generated into the “dist” folder of yo
ur project (if you project’s name is “
jaxws2
-
service
”, you’ll get the

jaxws2
-
service
.war” file).

NB: A WAR file is a ZIP archive file that contains the compiled source code of your application, its
configuration files, etc.
In other words: a
ll what is nee
ded to deploy your application on a server.

5

-

Deploy a
Web Service

You have two ways to deploy your WAR file: the
Web

administration interface of the
GlassFish

server, or
directly via NetBeans.

Deploy via the
Web

administration

interface

Make sure
GlassFish

is running.

-

In the left side panel, launch the “Applications” item menu.

-

Use the “Deploy” button.

-

The first option “
Packaged File to Be Uploaded to the Server
” allows you to upload the WAR file
to the server. The second option “
Local Packaged F
ile or Directory That Is Accessible from
GlassFish

Server
” allows you to navigate to the WAR file. It is useful if the
GlassFish

server is
located on a remote machine, and the WAR file is on this machine too. Make your choice and
select the WAR file to dep
loy.

6


The bundled Web Service tester

9


-

On the “
Deploy Applications or Modules
” screen :

o

Select the “
Web

Application” type. It would be already selected.

o

Choose a “context root”. The context root is the name of the sub
-
directory where your
application will be installed. Choose a simple name

or let the default choice. In our
example, we will use “
jaxws2
-
service
”.

o

Virtual Server: choose “server”.
GlassFish

is designed to support many server instances
and configuration. Since we have only one instance (the default instance shipped with
base ins
tallation), we’ll use it.

o

Validate with the “OK” button. The WAR fil
e is now deployed on the server:


Deploy via NetBeans

Simply do a right
-
click on your project and choose the “Deploy” option. The
NetBeans

output (Ctrl+4) will
show the deployment progress.

The WAR file is now deployed on GlassFish.

6


The bundled
Web Service

tester

The GlassFish
Web Service
s handler comes with a very useful feature: a
Web Service
s tester. For each
Web Service

you deploy, y
ou may be able to use a
Web

interface to consume
it
.

In the left
-
side panel of GlassFish, go to “Application
s
” and select the deployed application “jaxws2
-
service” in our example. In the “Modules and
Components
” table
, follow the “View Endpoint” link.


In

front of the “Tester” field, you’ll see a link to your
Web Service

tester (“
/jaxws2
-
service/WSDemo?Tester
”). Follow it: it lets you to choose between two protocols: HTTP or HTTPS links.
Make your choice (both may work).

Tip: The link may replace “localhos
t” by your machine’s name. Some
Web

browser
s

won’t be able to
associate this name to your machine. To make it work, simply replace the machine’s name by “localhost”
or “127.0.0.1”
; otherwise, edit your operating system’s ETC/HOSTS file.

7
-

Develop a Web Service client

10


Here is the tester
interface:


Put two integer values and use the “sum” button: if you see the expected result, it works! You can now
try the
last chapter of this tutorial:

develop a
Web Service

client.

7

-

Develop a
Web Service

client

Create a main class

Create a new Java
Application project with NetBeans (“File”, “New project”, “Java”, “Java Application”).
Create a main class. In our example, its name is “Main”, located into the “fr.tikione.jaxws2.client”

package
.

Retrieve the WSDL file of the
Web Service

The Metro toolkit

(and many of the JAX
-
WS 2.0 compliant toolkits) is able to generate a
Web Service

client easily. The only one thing to know about the
Web Service

is its WSDL file.

You can retrieve
the
Web Service

WSDL

from the GlassFish
Web

interface. In the left
-
side p
anel, go to
“Applications”, your application (“jaxws2
-
service”), the “View Endpoint” link, the link in front of the
“WSDL” field (something like “
/jaxws2
-
service/WSDemo?wsdl
”)
. Like the
Web Service

tester URL, you’ll
probably have to tweak the link.

You wi
ll now see a
WSDL (
XML
-
based)

file. Note its address (something like

http://localhost:8080/jaxws2
-
service/WSDemo?wsdl
”)
, we’ll need it later
.


7
-

Develop a Web Service client

11


Use the NetBeans/Metro assistant to generate a
Web Service

client

A simple
Web Service

client

NetBeans has an assistant which is able to produce a
Web Service

client. Actually, this is a GUI (Graphical
User Interface) for the Metro assistant:

-

D
o a right
-
click on your Java Application project, choose “N
ew”, “
Web Service

Client” (if this
option is not displayed, choose “Other…”, “
Web Service
s”, “
Web Service

Client”).

-

Choose the “WSDL URL” field and enter the WSDL URL we have seen previously.

-

Choose a package where the toolkit will generate the
Web Service

client. In our example, we will
use “
fr.tikione.jaxws2.client.generated
”.

-

Validate with the “Finish” button. The
Web Service

client will be generated into Java classes
located into the “fr.tikione.jaxws2.client.generated” package.

In the “Main” class, typ
e the following code:

package fr.tikione.jaxws2.client;


import fr.tikione.jaxws2.client.generated.WSDemo;

import fr.tikione.jaxws2.client.generated.WSDemo_Service;


public class Main {



public static void main(String[] args) {


try {


WSDemo_Service service = new WSDemo_Service();


WSDemo wsdemo = service.getWSDemoPort();


int result = wsdemo.sum(2, 15);


System.out.println("result:" + result);


} catch (Exception ex) {


ex.
printStackTrace();


}


}

}


This is our main class. Let’s examine its Java code:

-

Remember: we are trying to consume the “
WSDemo

Web
Service. NetBeans (via Metro) has
generated a client and named its Java classes according to the
Web Service
’s
name. So, we
import two classes from the “
fr.tikione.jaxws2.client.generated
” package: “
WSDemo
” and

WSDemo
_Service”. These two classes will allow us to consume the
Web Service
.

NB: the “WSDemo” class from the client and the other from the
Web Service

are
NOT the same
file. They only share the same name. Imagine the
Web Service

(project and WAR) has been
developed by a third
-
party company: you only know its WSDL; you don’t have any access to its
sources or compiled code

(
funnier
: this is a PHP
Web Service

v
ersion
!)
. As to the
Web Service

client, imagine it is developed by yourself, on your own computer.

I wanted to explain this point, because many beginners are confused about it.

7
-

Develop a Web Service client

12


-

The first line creates a “WSDemo_Service” class. This one will be able to inst
antiate our
Web
Service

client.

-

The second line is about the
Web Service

client instantiation. We use the
“get<
Web
ServiceName>Port” method of the “WSDemo_Service” object: ”get
WSDemo
Port”.

This object is a Java representation of the
Web Service

capabilities
. Since this
Web Service

publishes a “sum” method, our client object has a “sum” method too.

-

Third line: we simply call the “sum” method of the
Web Service
. We finish by showing the result
of the
Web Service
.

Compile (F11) the project and run (F6) it. If
you see the expected result, it works!

A more configurable
Web Service

client

There is a little problem: our
Web Service

client is designed to consume the
Web Service

located at a
hardcoded address (denoted by the WSDL address). If we choose to install the

Web Service

on another
machine, we won’t be able to consume it: the client will generate an error (it will indicate that it cannot
find the
Web Service

address).

The WSDL address is hardcoded because the NetBeans (Metro) assistant has retrieved a copy of
the
WSDL file and copied it into our client (check the “
META
-
INF.wsdl.localhost_8080.jaxws2
-
service

package).

We could
try to customize the copy of the WSDL file
:

it would be too much complicated and subject to
errors.

In addition, we would have to repeat

this step every time the client is generated.

The best way to consume a
Web Service

located at a non
-
static address is simply to set its address
programmatically, in our Java code. To do it, replace:

WSDemo_Service service = new WSDemo_Service();


By:

WS
Demo_Service service = new WSDemo_Service(new java.net.URL(


"http://localhost:8080/jaxws2
-
service/WSDemo?wsdl"));


This way, we can customize the
Web Service

WSDL address. If it moves to “http://www.tikione.fr/…”, we
simply edit this URL (to

“http://www.tikione.fr/jaxws2
-
service/WSDemo?wsdl”), and recompile our
project.



7
-

Develop a Web Service client

13







Congratulations, you have survived to this tutorial


Hope it helped you.

Don’t hesitate to send me comments: Jonathan Lermitage
<
jlermitage@netbeanscolors.org
>
.

My
Web
log:
http://netbeanscolors.org
, and Facebook:
https://www.facebook.com/jonathan.lermitage
.



You are
free to edit and redistribute this document. Simply don’t remove my name.