Oracle® Fusion Middleware: Developing and Securing Restful Web Services For Oracle Weblogic Server 12C (12.2.1)

[1]
Oracle
Fusion Middleware
Developing and Securing RESTful Web Services for Oracle

WebLogic Server
12c (12.2.1)
E55163-01
October 2015
Documentation for software developers that describes how
to develop Java EE web services that conform to the
Representational State Transfer (REST) architectural style
using Java API for RESTful Web Services (JAX-RS).
Oracle Fusion Middleware Developing and Securing RESTful Web Services for Oracle WebLogic Server, 12c
(12.2.1)
E55163-01
Copyright 2013, 2015 Oracle and/or its affiliates. All rights reserved.
This software and related documentation are provided under a license agreement containing restrictions on
use and disclosure and are protected by intellectual property laws. Except as expressly permitted in your
license agreement or allowed by law, you may not use, copy, reproduce, translate, broadcast, modify, license,
transmit, distribute, exhibit, perform, publish, or display any part, in any form, or by any means. Reverse
engineering, disassembly, or decompilation of this software, unless required by law for interoperability, is
prohibited.
The information contained herein is subject to change without notice and is not warranted to be error-free. If
you find any errors, please report them to us in writing.
If this is software or related documentation that is delivered to the U.S. Government or anyone licensing it
on behalf of the U.S. Government, then the following notice is applicable:
U.S. GOVERNMENT END USERS: Oracle programs, including any operating system, integrated software,
any programs installed on the hardware, and/or documentation, delivered to U.S. Government end users
are "commercial computer software" pursuant to the applicable Federal Acquisition Regulation and
agency-specific supplemental regulations. As such, use, duplication, disclosure, modification, and
adaptation of the programs, including any operating system, integrated software, any programs installed on
the hardware, and/or documentation, shall be subject to license terms and license restrictions applicable to
the programs. No other rights are granted to the U.S. Government.
This software or hardware is developed for general use in a variety of information management
applications. It is not developed or intended for use in any inherently dangerous applications, including
applications that may create a risk of personal injury. If you use this software or hardware in dangerous
applications, then you shall be responsible to take all appropriate fail-safe, backup, redundancy, and other
measures to ensure its safe use. Oracle Corporation and its affiliates disclaim any liability for any damages
caused by use of this software or hardware in dangerous applications.
Oracle and Java are registered trademarks of Oracle and/or its affiliates. Other names may be trademarks of
their respective owners.
Intel and Intel Xeon are trademarks or registered trademarks of Intel Corporation. All SPARC trademarks
are used under license and are trademarks or registered trademarks of SPARC International, Inc. AMD,
Opteron, the AMD logo, and the AMD Opteron logo are trademarks or registered trademarks of Advanced
Micro Devices. UNIX is a registered trademark of The Open Group.
This software or hardware and documentation may provide access to or information about content,
products, and services from third parties. Oracle Corporation and its affiliates are not responsible for and
expressly disclaim all warranties of any kind with respect to third-party content, products, and services
unless otherwise set forth in an applicable agreement between you and Oracle. Oracle Corporation and its
affiliates will not be responsible for any loss, costs, or damages incurred due to your access to or use of
third-party content, products, or services, except as set forth in an applicable agreement between you and
Oracle.
Contents
Preface ................................................................................................................................................................ vii
Documentation Accessibility ....................................................................................................................
Conventions ................................................................................................................................................
vii
vii
What's New in This Guide ........................................................................................................................ ix

New and Changed Features for Release 12c (12.2.1)..............................................................................
ix
x
x
1 Introduction to RESTful Web Services

1.1
1.2
1.3
1.4
1.5
Introduction to the REST Architectural Style .........................................................................

What are RESTful Web Services? .............................................................................................
Standards Supported for RESTful Web Service Development on WebLogic Server........
Roadmap for Implementing RESTful Web Services..............................................................
Learn More About RESTful Web Services ..............................................................................
1-1
1-2
1-2
1-3
1-4
2 Developing RESTful Web Services

2.1
2.1.1
2.1.2
2.2
2.3
2.3.1
2.3.2
2.3.3
2.4
2.4.1
2.4.2
2.4.3
2.4.4
2.4.5
2.5
2.5.1
2.5.2
About RESTful Web Service Development............................................................................. 2-1

Summary of Tasks to Develop RESTful Web Services................................................... 2-2
Example of a RESTful Web Service................................................................................... 2-3
Defining the Root Resource Class ............................................................................................ 2-3
Defining the Relative URI of the Root Resource and Subresources .................................... 2-3
How to Define the Relative URI of the Resource Class (@Path)................................... 2-4
How to Define the Relative URI of Subresources (@Path) ............................................ 2-5
What Happens at Runtime: How the Base URI is Constructed.................................... 2-5
Mapping Incoming HTTP Requests to Java Methods ........................................................... 2-6
About the Jersey Bookmark Sample ................................................................................. 2-7
How to Transmit a Representation of the Resource (@GET) ........................................ 2-7
How to Create or Update the Representation of the Resource (@PUT) ...................... 2-9
How to Delete a Representation of the Resource (@DELETE)...................................... 2-9
How to Create, Update, or Perform an Action on a Representation of the Resource
(@POST) 2-10
Customizing Media Types for the Request and Response Messages .............................. 2-10
How To Customize Media Types for the Request Message (@Consumes) ............. 2-11
How To Customize Media Types for the Response Message (@Produces) ............. 2-11
iii
2.5.3
2.6
2.6.1
2.6.2
2.6.3
2.6.4
2.7
2.8
2.9
2.10
2.11
2.12
2.13
What Happens At Runtime: How the Resource Method Is Selected for Response
Messages 2-12
Extracting Information From the Request Message............................................................
How to Extract Variable Information from the Request URI (@PathParam)...........
How to Extract Request Parameters (@QueryParam) .................................................
How to Define the DefaultValue (@DefaultValue)......................................................
Enabling the Encoding Parameter Values (@Encoded) ..............................................
Building Custom Response Messages ..................................................................................
Mapping HTTP Request and Response Entity Bodies Using Entity Providers..............
Accessing the Application Context .......................................................................................
Building URIs ...........................................................................................................................
Using Conditional GETs .........................................................................................................
Accessing the WADL...............................................................................................................
More Advanced RESTful Web Service Tasks ......................................................................
2-12
2-13
2-13
2-14
2-15
2-15
2-18
2-19
2-20
2-21
2-22
2-22
3 Developing RESTful Web Service Clients

3.1
3.2
3.3
Summary of Tasks to Develop RESTful Web Service Clients .............................................. 3-1

Example of a RESTful Web Service Client .............................................................................. 3-2
Invoking a RESTful Web Service from a Standalone Client................................................. 3-2
4 Building, Packaging, and Deploying RESTful Web Service Applications

4.1
Building RESTful Web Service Applications ..........................................................................
4.2
Packaging RESTful Web Service Applications .......................................................................
4.2.1
Packaging With an Application Subclass.........................................................................
4.2.2
Packaging With a Servlet....................................................................................................
4.2.2.1
How to Package the RESTful Web Service Application with Servlet 3.0.............
4.2.2.1.1
Packaging the RESTful Web Service Application Using web.xml With
Application Subclass 4-3
4.2.2.1.2
Packaging the RESTful Web Service Application Using web.xml Without
Application Subclass 4-4
4.2.2.2
How to Package the RESTful Web Service Application with Pre-3.0 Servlets ....
4.2.3
Packaging as a Default Resource.......................................................................................
4.3
Deploying RESTful Web Service Applications.......................................................................
4-1
4-1
4-2
4-3
4-3
4-5
4-7
4-7
5 Securing RESTful Web Services and Clients

5.1
5.2
5.3
5.4
5.5
About RESTful Web Service Security ......................................................................................

Securing RESTful Web Services and Clients Using OWSM Policies...................................
Securing RESTful Web Services Using web.xml ....................................................................
Securing RESTful Web Services Using SecurityContext .......................................................
Securing RESTful Web Services Using Java Security Annotations .....................................
5-1
5-1
5-2
5-3
5-4
6 Testing RESTful Web Services

7 Monitoring RESTful Web Services and Clients
7.1
iv
About Monitoring RESTful Web Services ............................................................................... 7-1
7.2
7.3
7.4
7.5
7.6
7.6.1
7.6.2
7.6.3
7.7
Monitoring RESTful Web Services Using Enterprise Manager Fusion Middleware Control .
7-2
Monitoring RESTful Web Services Using the Administration Console ............................. 7-2
Monitoring RESTful Web Services Using WLST.................................................................... 7-3
Enabling the Tracing Feature .................................................................................................... 7-6
Disabling RESTful Web Service Application Monitoring..................................................... 7-6
Disabling Monitoring for a RESTful Web Service Application Using Jersey Property.....
7-7
Disabling Monitoring for a RESTful Web Service Application Using WebLogic
Configuration MBean 7-9
Disabling RESTful Web Service Application Monitoring for a WebLogic Domain .. 7-9
Enable Monitoring of Synthetic Jersey Resources in a RESTful Web Service Application......
7-10
8 Using Server-Sent Events in WebLogic Server

8.1
8.2
8.3
Overview of Server-Sent Events (SSE)..................................................................................... 8-1

Understanding the WebLogic Server-Sent Events API ......................................................... 8-2
Sample Applications for Server-Sent Events .......................................................................... 8-2
A Compatibility with Earlier Jersey/JAX-RS Releases

A.1
Develop RESTful Web Service Clients Using Jersey 1.18 (JAX-RS 1.1 RI).........................
A.1.1
Example of a RESTful Web Service Client ......................................................................
A.1.2
Creating and Configuring a Client Instance ...................................................................
A.1.3
Creating a Web Resource Instance ...................................................................................
A.1.4
Sending Requests to the Resource....................................................................................
A.1.4.1
How to Build Requests ...............................................................................................
A.1.4.2
How to Send HTTP Requests ....................................................................................
A.1.4.3
How to Pass Query Parameters.................................................................................
A.1.4.4
How to Configure the Accept Header......................................................................
A.1.4.5
How to Add a Custom Header..................................................................................
A.1.4.6
How to Configure the Request Entity ......................................................................
A.1.5
Receiving a Response from a Resource ...........................................................................
A.1.5.1
How to Access the Status of Request........................................................................
A.1.5.2
How to Get the Response Entity ...............................................................................
A.1.6
More Advanced RESTful Web Service Client Tasks ...................................................
A.2
Support for Jersey 1.18 (JAX-RS 1.1 RI) Deployments Packaged with Pre-3.0 Servlets
A-1
A-2
A-3
A-4
A-5
A-5
A-6
A-7
A-8
A-8
A-8
A-9
A-9
A-9
A-10
A-10
vi
Preface
This preface describes the document accessibility features and conventions used in this
guideDeveloping and Securing RESTful Web Services for Oracle WebLogic Server.
Documentation Accessibility
For information about Oracle's commitment to accessibility, visit the Oracle
Accessibility Program website at
http://www.oracle.com/pls/topic/lookup?ctx=acc&id=docacc.
Access to Oracle Support
Oracle customers that have purchased support have access to electronic support
through My Oracle Support. For information, visit
http://www.oracle.com/pls/topic/lookup?ctx=acc&id=info or visit
http://www.oracle.com/pls/topic/lookup?ctx=acc&id=trs if you are hearing
impaired.
Conventions
The following text conventions are used in this document:
Convention
Meaning
boldface
Boldface type indicates graphical user interface elements associated

with an action, or terms defined in text or the glossary.
italic
Italic type indicates book titles, emphasis, or placeholder variables for

which you supply particular values.
monospace
Monospace type indicates commands within a paragraph, URLs, code

in examples, text that appears on the screen, or text that you enter.
vii
viii
What's New in This Guide

The following topics introduce the new and changed features of RESTful web services
and provides pointers to additional information. This document was released initially
in Oracle Fusion Middleware 12c Release 1 (12.1.1).
New and Changed Features for Release 12c (12.2.1)

Oracle Fusion Middleware Release 12c (12.2.1) includes the following new and
changed features for this document.
Provides support for Jersey 2.x (JAX-RS 2.0 RI) by default in this release.
Registration as a shared library with WebLogic Server is no longer required.
Provides enhanced monitoring of RESTful web services in the WebLogic
Administration Console, including enhanced runtime statistics for your RESTful
applications and resources, detailed deployment and configuration data, global
execution statistics, and resource and resource method execution statistics. For
more information, see Chapter 7, "Monitoring RESTful Web Services and Clients."
Includes the ability to disable RESTful web services monitoring at the individual
application level, or globally at the domain level. For more information, see
"Disabling RESTful Web Service Application Monitoring" on page 7-6.
Reflects support for the Jersey 2.21.1 JAX-RS 2.0 RI.
Supports securing Jersey 2.x (JAX-RS 2.0 RI) web services using Oracle Web
Services Manager (OWSM) security policies. For more information, see "Securing
RESTful Web Services and Clients Using OWSM Policies" on page 5-1.
Adds support for Java EE 7.
The Jersey 1.x client API is deprecated. It is recommended that you update your
RESTful client applications to use the JAX-RS 2.0 client APIs at your earliest
convenience.
Removes support for the Jersey 1.x (JAX-RS 1.1. RI) server APIs. You should use
the corresponding standard JAX-RS 2.0 or Jersey 2.x APIs instead.
Note: Support for the Jersey 1.18 (JAX-RS 1.1RI) client APIs are
deprecated in this release of WebLogic Server but are maintained for
backward compatibility. For more information, see "Develop RESTful
Web Service Clients Using Jersey 1.18 (JAX-RS 1.1 RI)" on page A-1.
It is recommended that you update your RESTful client applications

to use the JAX-RS 2.0 client APIs at your earliest convenience.
ix

Oracle Fusion Middleware Release 12c (12.1.3) includes the following new and
changed features for this document.
Reflects support of the Jersey 2.5.1 Java API for RESTful Web Services (JAX-RS) 2.0
Reference Implementation (RI) as a pre-built shared library.
Reflects support for the Jersey 1.18 JAX-RS 1.1. RI.

Oracle Fusion Middleware 12c (12.1.2) includes the following new and changed
features for this document.
Secure RESTful web services using Oracle Web Services Manager (OWSM)
policies. For more information, see "Securing RESTful Web Services and Clients
Using OWSM Policies" on page 5-1.
New standalone web service client JAR files that support basic RESTful web
service client-side functionality and Oracle Web Services Manager (OWSM)
security policy support. See "Invoking a RESTful Web Service from a Standalone
Client" on page 3-2.
1
Introduction to RESTful Web Services
1
This chapter provides an overview of developing Java EE web services that conform to
the Representational State Transfer (REST) architectural style using Java API for
RESTful Web Services (JAX-RS).
[2]
This chapter includes the following sections:
Introduction to the REST Architectural Style
What are RESTful Web Services?
Standards Supported for RESTful Web Service Development on WebLogic Server
Roadmap for Implementing RESTful Web Services
Learn More About RESTful Web Services
For definitions of unfamiliar terms found in this and other books, see the Glossary.
1.1 Introduction to the REST Architectural Style

REST describes any simple interface that transmits data over a standardized interface
(such as HTTP) without an additional messaging layer, such as Simple Object Access
Protocol (SOAP). REST is an architectural stylenot a toolkitthat provides a set of
design rules for creating stateless services that are viewed as resources, or sources of
specific information (data and functionality). Each resource can be identified by its
unique Uniform Resource Identifiers (URIs).
A client accesses a resource using the URI and a standardized fixed set of methods,
and a representation of the resource is returned. A representation of a resource is
typically a document that captures the current or intended state of a resource. The
client is said to transfer state with each new resource representation.
Table 11 defines a set of constraints defined by the REST architectural style that must
be adhered to in order for an application to be considered "RESTful."
1-1
What are RESTful Web Services?
Table 11
Constraints of the REST Architectural Style
Constraint
Description
Addressability
Identifies all resources using a uniform resource identifier (URI). In the English
language, URIs would be the equivalent of a noun.
Uniform interface
Enables the access of a resource using a uniform interface, such as HTTP methods
(GET, POST, PUT, and DELETE). Applying the English language analogy, these
methods would be considered verbs, describing the actions that are applicable to the
named resource.
Client-server architecture
Separates clients and servers into interface requirements and data storage
requirements. This architecture improves portability of the user interface across
multiple platforms and scalability by simplifying server components.
Stateless interaction
Uses a stateless communication protocol, typically Hypertext Transport Protocol

(HTTP). All requests must contain all of the information required for a particular
request. Session state is stored on the client only.
This interactive style improves:
VisibilitySingle request provides the full details of the request.
ReliabilityEases recovery from partial failures.
ScalabilityNot having to store state enables the server to free resources quickly.
Cacheable
Enables the caching of client responses. Responses must be identified as cacheable or

non-cacheable. Caching eliminates some interactions, improving efficiency, scalability,
and perceived performance.
Layered system
Enables client to connect to an intermediary server rather than directly to the end
server (without the client's knowledge). Use of intermediary servers improve system
scalability by offering load balancing and shared caching.
1.2 What are RESTful Web Services?

RESTful web services are services that are built according to REST principles and, as
such, are designed to work well on the Web.
RESTful web services conform to the architectural style constraints defined in
Table 11. Typically, RESTful web services are built on the HTTP protocol and
implement operations that map to the common HTTP methods, such as GET, POST,
PUT, and DELETE to retrieve, create, update, and delete resources, respectively.
1.3 Standards Supported for RESTful Web Service Development on

WebLogic Server
The JAX-RS provides support for creating web services according to REST
architectural style. JAX-RS uses annotations to simplify the development of RESTful
web services. By simply adding annotations to your web service, you can define the
resources and the actions that can be performed on those resources. JAX-RS is part of
the Java EE 7 full profile, and is integrated with Contexts and Dependency Injection
(CDI) for the Java EE Platform (CDI), Enterprise JavaBeans (EJB) technology, and Java
Servlet technology.
WebLogic Server supports the following JAX-RS API and Reference Implementation
(RI):
JAX-RS 2.0 Rev a
Jersey 2.21.1
1-2 Developing and Securing RESTful Web Services for Oracle WebLogic Server
Roadmap for Implementing RESTful Web Services
Notes: Jersey 2.x (JAX-RS 2.0 RI) support is provided by default in

this release of WebLogic Server. Registration as a shared library is no
longer required.
The Jersey 1.x server-side APIs are no longer supported. You should
use the corresponding standard JAX-RS 2.0 or Jersey 2.x APIs instead.
The Jersey 1.x client API is deprecated. It is recommended that you
update your RESTful client applications to use the JAX-RS 2.0 client
APIs at your earliest convenience.
The Jersey 2.x (JAX-RS 2.0 RI) includes the following functionality:
Jersey
JAX-RS API
JSON processing and streaming
Table 12 lists key features delivered with Jersey 2.x (JAX-RS 2.0 RI).
Table 12
Key Features in Jersey 2.x (JAX-RS 2.0 RI)
Key Feature
Description
Client API
Communicate with RESTful web services in a standard way. The Client API facilitates
the consumption of a web service exposed via HTTP protocol and enables developers
to concisely and efficiently implement portable client-side solutions that leverage
existing and well established client-side HTTP connector implementations.
For complete details, see:
Asynchronous
communication
"Client API" in Jersey 2.21 User Guide
"Accessing REST Resources with the JAX-RS Client API" in Java EE 7 Tutorial
Invoke and process requests asynchronously.

For complete details, see:
Filters and interceptors
"Asynchronous Services and Clients" in the Jersey 2.21 User Guide
"Advanced Features of the Client API" in Java EE 7 Tutorial
Using filters, modify inbound and outbound requests and responses., such as header
information. Using interceptors, modify entity input and output streams. Filters and
interceptors can be used on both the client and server side.
For complete details, see "Filters and Interceptors" in the Jersey 2.21 User Guide.
For more information about JAX-RS and samples, see Section 1.5, "Learn More About
RESTful Web Services."
1.4 Roadmap for Implementing RESTful Web Services

Table 13 provides a roadmap of common tasks for developing, packaging and
deploying, securing and monitoring RESTful web services and clients.
1-3
Learn More About RESTful Web Services
Table 13
Roadmap for Implementing RESTful Web Services and Clients
Task
More Information
Develop RESTful web services.
Chapter 2, "Developing RESTful Web Services"
Develop clients to invoke the RESTful web services.
Section 3.1, "Summary of Tasks to Develop

RESTful Web Service Clients"
Package and deploy RESTful web services.
Secure RESTful web services.
Section 4.2.1, "Packaging With an Application

Subclass"
Section 4.2.2, "Packaging With a Servlet"
Section 4.2.3, "Packaging as a Default
Resource"
Section 5.3, "Securing RESTful Web Services
Using web.xml"
Using SecurityContext"
Using Java Security Annotations"
Test RESTful web services.
Chapter 6, "Testing RESTful Web Services"
Monitor RESTful web services.
Chapter 7, "Monitoring RESTful Web Services and

Clients"
(Optional) Migrate existing applications from Jersey 1.x to 2.x.
"Migration Guide" in Jersey 2.21 User Guide
1.5 Learn More About RESTful Web Services

Table 1.5 provides a list of resources for more information about RESTful web services.
Table 14
Resources for More Information
Resource
Link
Jersey User Guide
Jersey 2.21 User Guide
Jersey API Javadoc
Jersey 2.21 API Documentation
Community Wiki for

Project Jersey
https://jersey.java.net/
JSR-339 JAX-RS 2.0

Specification
https://jcp.org/en/jsr/detail?id=339
JAX-RS API Javadoc
https://jax-rs-spec.java.net/nonav/2.0-rev-a/apidocs/index.html
JAX-RS Project
https://jax-rs-spec.java.net/
RESTful Web Services

(JAX-RS) sample
"Sample Application and Code Examples" in Understanding Oracle WebLogic Server
The Java EE 7
TutorialBuilding
RESTful Web Services
With JAX-RS
http://docs.oracle.com/javaee/7/tutorial/jaxrs.htm
"Representational State
Transfer (REST)" in
Architectural Styles and the
Design of Network-based
Software Architectures
(Dissertation by Roy
Fielding)
http://www.ics.uci.edu/~fielding/pubs/dissertation/rest_arch_style.htm
2
Developing RESTful Web Services
2
This chapter describes how to develop Java EE web services that conform to the
Representational State Transfer (REST) architectural style using Java API for RESTful
Web Services (JAX-RS).
[3]
About RESTful Web Service Development
Defining the Root Resource Class
Defining the Relative URI of the Root Resource and Subresources
Mapping Incoming HTTP Requests to Java Methods
Customizing Media Types for the Request and Response Messages
Extracting Information From the Request Message
Building Custom Response Messages
Mapping HTTP Request and Response Entity Bodies Using Entity Providers
Accessing the Application Context
Building URIs
Using Conditional GETs
Accessing the WADL
More Advanced RESTful Web Service Tasks
2.1 About RESTful Web Service Development

JAX-RS is a Java programming language API that uses annotations to simplify the
development of RESTful web services. JAX-RS annotations are runtime annotations.
When you deploy the Java EE application archive containing JAX-RS resource classes
to WebLogic Server, as described in Chapter 4, "Building, Packaging, and Deploying
RESTful Web Service Applications," the runtime configures the resources, generates
the helper classes and artifacts, and exposes the resource to clients.
The following sections provide more information about RESTful web service
development:
Section 2.1.1, "Summary of Tasks to Develop RESTful Web Services"
Section 2.1.2, "Example of a RESTful Web Service"
Developing RESTful Web Services 2-1
About RESTful Web Service Development
For information about developing RESTful web services using Oracle JDeveloper, see
"Creating RESTful Web Services and Clients" in Developing Applications with Oracle
JDeveloper.
2.1.1 Summary of Tasks to Develop RESTful Web Services

Table 21 summarizes a subset of the tasks that are required to develop RESTful web
service using JAX-RS annotations. For more information about advanced tasks, see
Section 2.13, "More Advanced RESTful Web Service Tasks."
Note: In addition to the development tasks described in Table 21,
you may wish to take advantage of features available with Jersey 2.x
(JAX-RS 2.0 RI) when developing your RESTful web services. For a list
of key features, see Table 12, " Key Features in Jersey 2.x (JAX-RS 2.0
RI)".
Table 21
Summary of Tasks to Develop RESTful Web Services
Task
More Information
Define the root resource class.
Section 2.2, "Defining the Root Resource Class"
Define the relative URI of the root resource class

and its methods using the @Path annotation.
Section 2.3, "Defining the Relative URI of the Root

Resource and Subresources"
If you define the @Path annotation using a variable,

you can assign a value to it using the @PathParam
annotation.
Map incoming HTTP requests to your Java methods Section 2.4, "Mapping Incoming HTTP Requests to
using @GET, @POST, @PUT, or @DELETE, to get, create,
Java Methods"
update, or delete representations of the resource,
respectively.
Customize the request and response messages, as
required, to specify the MIME media types of
representations a resource can produce and
consume.
Section 2.5, "Customizing Media Types for the

Request and Response Messages"
Extract information from the request.
Section 2.6, "Extracting Information From the

Request Message"
Build custom response messages to customize

response codes or include additional metadata.
Section 2.7, "Building Custom Response Messages"
Access information about the application

deployment context or the context of individual
requests.
Section 2.9, "Accessing the Application Context"
Build new or extend existing resource URIs.
Section 2.10, "Building URIs"
Evaluate one or more preconditions before

processing a GET request, potentially reducing
bandwidth and improving server performance.
Section 2.11, "Using Conditional GETs"
Access the WADL.
Section 2.12, "Accessing the WADL"
Optionally, create a class that extends

javax.ws.rs.core.Application to define the
components of a RESTful web service application
deployment and provides additional metadata.
Section 4.2.1, "Packaging With an Application

Subclass"
Secure your RESTful web services.
Chapter 5, "Securing RESTful Web Services and

Clients"
2.1.2 Example of a RESTful Web Service

Example 21 provides a simple example of a RESTful web service. In this example:
The helloWorld class is a resource with a relative URI path defined as

/helloworld. At runtime, if the context root for the WAR file is defined as
http://examples.com, the full URI to access the resource is
http://examples.com/helloworld. For more information, see Section 2.3,
"Defining the Relative URI of the Root Resource and Subresources."
The sayHello method supports the HTTP GET method. For more information, see
Section 2.4, "Mapping Incoming HTTP Requests to Java Methods."
The sayHello method produces content of the MIME media type text/plain. For
more information, see Section 2.5, "Customizing Media Types for the Request and
Response Messages."
Additional examples are listed in Section 1.5, "Learn More About RESTful Web
Services."
Example 21
Simple RESTful Web Service
package samples.helloworld;
import javax.ws.rs.GET;
import javax.ws.rs.Path;
import javax.ws.rs.Produces;
// Specifies the path to the RESTful service
@Path("/helloworld")
public class helloWorld {
// Specifies that the method processes HTTP GET requests
@GET
@Produces("text/plain")
public String sayHello() {
return "Hello World!";
}
}
2.2 Defining the Root Resource Class

A root resource class is a Plain Old Java Object (POJO) for which one or both of the
following statements are true:
Is annotated with @Path. For more information, see Section 2.3, "Defining the
Relative URI of the Root Resource and Subresources."
Has at least one method annotated with @Path or with a request method designator,
such as @GET, @POST, @PUT, or @DELETE. A resource method is a method in the
resource class that is annotated using a request method designator. For more
information, see Section 2.4, "Mapping Incoming HTTP Requests to Java
Methods."
2.3 Defining the Relative URI of the Root Resource and Subresources
Add the javax.ws.rs.Path annotation at the class level of the resource to define the
relative URI of the RESTful web service. Such classes are referred to a root resource
classes. You can add @Path on methods of the root resource class as well, to define
subresources to group specific functionality.
The following sections describe how to define the relative URI of the root resource and
subresources:
Section 2.3.1, "How to Define the Relative URI of the Resource Class (@Path)"
Section 2.3.2, "How to Define the Relative URI of Subresources (@Path)"
Section 2.3.3, "What Happens at Runtime: How the Base URI is Constructed"
2.3.1 How to Define the Relative URI of the Resource Class (@Path)
The @Path annotation defines the relative URI path for the resource, and can be
defined as a constant or variable value (referred to as "URI path template"). You can
add the @Path annotation at the class or method level.
To define the URI as a constant value, pass a constant value to the @Path annotation.
Preceding and ending slashes (/) are optional.
In Example 22, the relative URI for the resource class is defined as the constant value,
/helloworld.
Example 22
Defining the Relative URI as a Constant Value
...
public class helloWorld {. . .}
To define the URI as a URI path template, pass one or more variable values enclosed in
braces in the @Path annotation. Then, you can use the javax.ws.rs.PathParam
annotation to extract variable information from the request URI, defined by the @Path
annotation, and initialize the value of the method parameter, as described in
Section 2.6.1, "How to Extract Variable Information from the Request URI
(@PathParam)."
In Example 23, the relative URI for the resource class is defined using a variable,
enclosed in braces, for example, /users/{username}.
Example 23
Defining the Relative URI as a Variable Value
...
@Path("/users/{username}")
public class helloWorld {. . .}
}
To further customize the variable, you can override the default regular expression of
"[^/]+?" by specifying the expected regular expression as part of the variable
definition. For example:
@Path("users/{username: [a-zA-Z][a-zA-Z_0-9]}")
In this example, the username variable will match only user names that begin with one
uppercase or lowercase letter followed by zero or more alphanumeric characters or the
underscore character. If the username does not match the requirements, a 404 (Not
Found) response will be sent to the client.
For more information, see the @Path annotation in the Java EE 7 Specification APIs.
2.3.2 How to Define the Relative URI of Subresources (@Path)

Add the javax.ws.rs.Path annotation to the method of a resource to define a
subresource. Subresources enable users to group specific functionality for a resource.
In Example 23, if the request path of the URI is users/list, then the getUserList
subresource method is matched and a list of users is returned.
Example 24
Defining a Subresource
@Path("/users")
public class UserResource {
. . .
@GET
@Path("/list")
public String getUserList() {
...
}
}
2.3.3 What Happens at Runtime: How the Base URI is Constructed

The base URI is constructed as follows:
http://myHostName/contextPath/servletURI/resourceURI
myHostNameDNS name mapped to the Web Server. You can replace this with
host:port which specifies the name of the machine running WebLogic Server and
the port used to listen for requests.
contextPathName of the standalone Web application. The Web application
name is specified in the META-INF/application.xml deployment descriptor in an
EAR file or the weblogic.xml deployment descriptor in a WAR file. If not
specified, it defaults to the name of the WAR file minus the .war extension. For
more information, see "context-root" in Developing Web Applications, Servlets, and
JSPs for Oracle WebLogic Server.
servletURIBase URI for the servlet context path. This path is configured as part
of the packaging options defined in Table 41. Specifically, you can define the
servlet context path by:
Updating the web.xml deployment descriptor to define the servlet mapping.
Adding a javax.ws.rs.ApplicationPath annotation to the class that extends

javax.ws.rs.core.Application, if defined.
If the servlet context path is configured using both options above, then the servlet
mapping takes precedence. If you do not configure the servlet context path in your
configuration using either of the options specified above, the WebLogic Server
provides a default RESTful web service application context path, resources. For
more information, see Chapter 4, "Building, Packaging, and Deploying RESTful
Web Service Applications."
resourceURI@Path value specified for the resource or subresource. This path

may be constructed from multiple resources and subresources @Path values.
In Example 22, at runtime, if the context path for the WAR file is defined as rest and
the default URI for the servlet (resources) is in effect, the base URI to access the
resource is http://myServer:7001/rest/resources/helloworld.
In Example 23, at runtime, the base URI will be constructed based on the value
specified for the variable. For example, if the user entered johnsmith as the username,
the base URI to access the resource is
http://myServer:7001/rest/resources/users/johnsmith.
2.4 Mapping Incoming HTTP Requests to Java Methods

JAX-RS uses Java annotations to map an incoming HTTP request to a Java method.
Table 22 lists the annotations available, which map to the similarly named HTTP
methods.
Table 22
javax.ws.rs Annotations for Mapping HTTP Requests to Java Methods
Annotation
Description
Idempotent
@GET
Transmits a representation of the resource identified by the URI to the client.

The format might be HTML, plain text, JPEG, and so on. See Section 2.4.2,
"How to Transmit a Representation of the Resource (@GET)."
Yes
@PUT
Creates or updates the representation of the specified resource identified by

the URI. See Section 2.4.3, "How to Create or Update the Representation of
the Resource (@PUT)."
Yes
@DELETE
Deletes the representation of the resource identified by the URI. See

Section 2.4.4, "How to Delete a Representation of the Resource (@DELETE)."
Yes
@POST
Creates, updates, or performs an action on the representation of the specified No

resource identified by the URI. See Section 2.4.5, "How to Create, Update, or
Perform an Action on a Representation of the Resource (@POST)."
@HEAD
Returns the response headers only, and not the actual resource (that is, no
message body). This is useful to save bandwidth to check characteristics of a
resource without actually downloading it. For more information, see the
@HEAD annotation in the Java EE 7 Specification APIs.
Yes
The HEAD method is implemented automatically if not implemented

explicitly. In this case, the runtime invokes the implemented GET method, if
present, and ignores the response entity, if set.
@OPTIONS
Returns the communication options that are available on the

request/response chain for the specified resource identified by the URI. The
Allow response header will be set to the set of HTTP methods supported by
the resource and the WADL file is returned. For more information, see the
@OPTIONS annotation in the Java EE 7 Specification APIs.
Yes
The OPTIONS method is implemented automatically if not implemented

explicitly. In this case, the Allow response header is set to the set of HTTP
methods supported by the resource and the WADL describing the resource is
returned.
@HttpMethod
Indicates that the annotated method should be used to handle HTTP

requests. For more information, see the @HttpMethod annotation in the Java
EE 7 Specification APIs.
N/A
The following sections provide more information about the JAX-RS annotations used
for mapping HTTP requests to Java methods.
Section 2.4.1, "About the Jersey Bookmark Sample"
Section 2.4.2, "How to Transmit a Representation of the Resource (@GET)"
Section 2.4.3, "How to Create or Update the Representation of the Resource

(@PUT)"
Section 2.4.4, "How to Delete a Representation of the Resource (@DELETE)"
Section 2.4.5, "How to Create, Update, or Perform an Action on a Representation of
the Resource (@POST)"
2.4.1 About the Jersey Bookmark Sample

The examples referenced in the following sections are excerpted from the bookmark
sample that is delivered with Jersey 2.x (JAX-RS 2.0 RI). The bookmark sample
provides a Web application that maintains users and the browser bookmarks that they
set.
The following table summarizes the resource classes in the sample, their associated
URI path, and the HTTP methods demonstrated by each class.
Table 23
About the Jersey Bookmark Sample
Resource Class
URI Path
HTTP Methods Demonstrated
UsersResource
/users
GET
UserResource
/users/{userid}
GET, PUT, DELETE
BookmarksResource
/users/{userid}/bookmarks
GET, POST
BookmarkResource
/users/{userid}/bookmarks/{bmid}
GET. PUT, DELETE
The bookmark sample, and other Jersey samples, can be accessed in one of the
following ways:
Accessing the bookmark sample at

https://repo1.maven.org/maven2/org/glassfish/jersey/examples/bookmark/
Browsing the bookmark sample source code on GitHub:
https://github.com/jersey/jersey/tree/master/examples/bookmark
Browsing the Maven repositories for all Jersey examples, including a WebLogic
Server-specific example bundle for each version, at:
https://repo1.maven.org/maven2/org/glassfish/jersey/bundles/jersey-exam
ples/
2.4.2 How to Transmit a Representation of the Resource (@GET)

The javax.ws.rs.GET annotation transmits a representation of the resource identified
by the URI to the client. The format or the representation returned in the response
entity-body might be HTML, plain text, JPEG, and so on. For more information, see the
@GET annotation in the Java EE 7 Specification APIs.
In Example 25, the annotated Java method, getBookmarkAsJsonArray, from the
BookmarksResource class in the Jersey bookmark sample, will process HTTP GET
requests. For more information about the Jersey bookmark sample, see Section 2.4.1,
"About the Jersey Bookmark Sample."
Example 25
Mapping the HTTP GET Request to a Java Method (BookmarksResource Class)
...
public class BookmarksResource {
...
@Path("{bmid: .+}")
public BookmarkResource getBookmark(@PathParam("bmid") String bmid) {
return new BookmarkResource(uriInfo, em,
userResource.getUserEntity(), bmid);
}
@GET
@Produces(MediaType.APPLICATION_JSON)
public JSONArray getBookmarksAsJsonArray() {
JSONArray uriArray = new JSONArray();
for (BookmarkEntity bookmarkEntity : getBookmarks()) {
UriBuilder ub = uriInfo.getAbsolutePathBuilder();
URI bookmarkUri = ub.
path(bookmarkEntity.getBookmarkEntityPK().getBmid()).
build();
uriArray.put(bookmarkUri.toASCIIString());
}
return uriArray;
}
...
}
In Example 26, the annotated Java method, getBookmark, from the BookmarkResource
class in the Jersey bookmark sample, will process HTTP GET requests. This example
shows how to process the JSON object that is returned. For more information about the
Jersey bookmark sample, see Section 2.4.1, "About the Jersey Bookmark Sample."
Example 26
Mapping the HTTP GET Request to a Java Method (BookmarkResource Class)
...
public class BookmarkResource {
...
@GET
@Produces(MediaType.APPLICATION_JSON)
public JSONObject getBookmark() {
return asJson();
}
...
public JSONObject asJson() {
try {
return new JSONObject()
.put("userid", bookmarkEntity.getBookmarkEntityPK().getUserid())
.put("sdesc", bookmarkEntity.getSdesc())
.put("ldesc", bookmarkEntity.getLdesc())
.put("uri", bookmarkEntity.getUri());
} catch (JSONException je){
return null;
}
}
}
2.4.3 How to Create or Update the Representation of the Resource (@PUT)

The javax.ws.rs.PUT annotation creates or updates the representation of the specified
resource identified by the URI. For more information, see the @PUT annotation in the
Java EE 7 Specification APIs.
In Example 27, the annotated Java method, putBookmark, from the BookmarkResource
class in the Jersey bookmark sample, will process HTTP PUT requests and update the
specified bookmark. For more information about the Jersey bookmark sample, see
Section 2.4.1, "About the Jersey Bookmark Sample."
Example 27
Mapping the HTTP PUT Request to a Java Method
import javax.ws.rs.PUT;
...
...
@PUT
@Consumes(MediaType.APPLICATION_JSON)
public void putBookmark(JSONObject jsonEntity) throws JSONException {
bookmarkEntity.setLdesc(jsonEntity.getString("ldesc"));
bookmarkEntity.setSdesc(jsonEntity.getString("sdesc"));
bookmarkEntity.setUpdated(new Date());
TransactionManager.manage(new Transactional(em) {
public void transact() {
em.merge(bookmarkEntity);
}});
}
}
2.4.4 How to Delete a Representation of the Resource (@DELETE)

The javax.ws.rs.DELETE annotation deletes the representation of the specified
resource identified by the URI. The response entity-body may return a status message
or may be empty. For more information, see the @DELETE annotation in the Java EE 7
Specification APIs.
In Example 28, the annotated Java method, deleteBookmark, from the
BookmarkResource class in the Jersey bookmark sample, will process HTTP DELETE
requests, and delete the specified bookmark. For more information about the Jersey
bookmark sample, see Section 2.4.1, "About the Jersey Bookmark Sample."
Example 28
Mapping the HTTP DELETE Request to a Java Method
import javax.ws.rs.DELETE;
...
...
@DELETE
public void deleteBookmark() {
UserEntity userEntity = bookmarkEntity.getUserEntity();

userEntity.getBookmarkEntityCollection().remove(bookmarkEntity);
em.merge(userEntity);
em.remove(bookmarkEntity);
}});
}
}
2.4.5 How to Create, Update, or Perform an Action on a Representation of the Resource

(@POST)
The javax.ws.rs.POST annotation creates, updates, or performs an action on the
representation of the specified resource identified by the URI. For more information,
see the @POST annotation in the Java EE 7 Specification APIs.
In Example 29, the annotated Java method, postForm, from the BookmarksResource
class in the Jersey bookmark sample, will process HTTP POST requests, and update
the specified information. For more information about the Jersey bookmark sample,
see Section 2.4.1, "About the Jersey Bookmark Sample."
Example 29
Mapping the HTTP POST Request to a Java Method
import javax.ws.rs.POST;
...
public class BookmarksResource {
...
@POST
@Consumes(MediaType.APPLICATION_JSON)
public Response postForm(JSONObject bookmark) throws JSONException {
final BookmarkEntity bookmarkEntity = new
BookmarkEntity(getBookmarkId(bookmark.getString("uri")),
userResource.getUserEntity().getUserid());
bookmarkEntity.setUri(bookmark.getString("uri"));
bookmarkEntity.setUpdated(new Date());
bookmarkEntity.setSdesc(bookmark.getString("sdesc"));
bookmarkEntity.setLdesc(bookmark.getString("ldesc"));
userResource.getUserEntity().getBookmarkEntityCollection().add(bookmarkEntity);
em.merge(userResource.getUserEntity());
}});
URI bookmarkUri = uriInfo.getAbsolutePathBuilder().
path(bookmarkEntity.getBookmarkEntityPK().getBmid()).
build();
return Response.created(bookmarkUri).build();
}
}
2.5 Customizing Media Types for the Request and Response Messages
Add the javax.ws.rs.Consumes or javax.ws.rs.Produces annotation at the class level
of the resource to customize the request and response media types, as described in the
following sections:
Section 2.5.1, "How To Customize Media Types for the Request Message
(@Consumes)"
Section 2.5.2, "How To Customize Media Types for the Response Message
(@Produces)"
Section 2.5.3, "What Happens At Runtime: How the Resource Method Is Selected
for Response Messages"
2.5.1 How To Customize Media Types for the Request Message (@Consumes)
The javax.ws.rs.Consumes annotation enables you to specify the MIME media types
of representations a resource can consume that were sent from the client. The
@Consumes annotation can be specified at both the class and method levels and more
than one media type can be declared in the same @Consumes declaration.
If there are no methods in a resource that can consume the specified MIME media
types, the runtime returns an HTTP 415 Unsupported Media Type error.
For more information, see the @Consumes annotation in the Java EE 7 Specification APIs.
In Example 211, the @Consumes annotation defined for the Java class, helloWorld,
specifies that the class produces messages using the text/plain MIME media type.
Example 210
Customizing the Media Types for the Request Message Using @Consumes
package samples.consumes;
import javax.ws.rs.Consumes;
import javax.ws.rs.POST;
...
...
@POST
@Consumes("text/plain")
public void postMessage(String message) {
// Store the message
}
}
2.5.2 How To Customize Media Types for the Response Message (@Produces)
The javax.ws.rs.Produces annotation enables you to specify the MIME media types
of representations a resource can produce and send back to the client. The @Produces
annotation can be specified at both the class and method levels and more than one
media type can be declared in the same @Produces declaration.
If there are no methods in a resource that can produce the specified MIME media
types, the runtime returns an HTTP 406 Not Acceptable error.
For more information, see the @Produces annotation in the Java EE 7 Specification APIs.
In Example 211, the @Produces annotation specified for the Java class, SomeResource,
specifies that the class produces messages using the text/plain MIME media type.
The doGetAsPlainText method defaults to the MIME media type specified at the class
level. The doGetAsHtml method overrides the class-level setting and specifies that the
method produces HTML rather than plain text.
Example 211
Customizing the Media Types for the Response Using @Produces
package samples.produces;
@Path("/myResource")
public class SomeResource {
@GET
public String doGetAsPlainText() { ... }
@GET
@Produces("text/html")
public String doGetAsHtml() { ... }
}
2.5.3 What Happens At Runtime: How the Resource Method Is Selected for Response
Messages
If a resource class is capable of producing more that one MIME media type, then the
resource method that is selected corresponds to the acceptable media type declared in
the Accept header of the HTTP request. In Example 211, if the Accept header is
Accept: text/html, then the doGetAsPlainText method is invoked.
If multiple MIME media types are included in the @Produces annotation and both are
acceptable to the client, the first media type specified is used. In Example 211, if the
Accept header is Accept: application/html, application/text, then the
doGetAsHtml method is invoked and the application/html MIME media type is used
as it is listed first in the list.
2.6 Extracting Information From the Request Message

The javax.ws.rs package defines a set of annotations, shown in Table 24, that enable
you extract information from the request message to inject into parameters of your
Java method.
Table 24
javax.ws.rs Annotations for Extracting Information From the Request Message
Annotation
Description
@BeanParam
Inject aggregated request parameters into a single bean. For more information, see the
@BeanParam annotation in the Java EE 7 Specification APIs.
For additional usage information, see "Parameter Annotations (@*Param)" in the Jersey 2.21
User Guide.
@CookieParam
Extract information from the HTTP cookie-related headers to initialize the value of a method
parameter. For more information, see the @CookieParam annotation in the Java EE 7
Specification APIs.
@DefaultValue
Define the default value of the request metadata that is bound using one of the following
annotations: @CookieParam, @FormParam, @HeaderParam, @MatrixParam, @PathParam, or
@QueryParam. For more information, see Section 2.6.3, "How to Define the DefaultValue
(@DefaultValue)."
@Encoded
Enable encoding of a parameter value that is bound using one of the following annotations:
@FormParam, @MatrixParam, @PathParam, or @QueryParam. For more information, see
Section 2.6.4, "Enabling the Encoding Parameter Values (@Encoded)."
@FormParam
Extract information from an HTML form of the type application/x-www-form-urlencoded.

For more information, see the @FormParam annotation in the Java EE 7 Specification APIs.
Table 24 (Cont.) javax.ws.rs Annotations for Extracting Information From the Request Message
Annotation
Description
@HeaderParam
Extract information from the HTTP headers to initialize the value of a method parameter.
For more information, see the @HeaderParam annotation in the Java EE 7 Specification APIs.
@MatrixParam
Extract information from the URI path segments to initialize the value of a method
parameter. For more information, see the @MatrixParam annotation in the Java EE 7
Specification APIs.
@PathParam
Define the relative URI as a variable value (referred to as "URI path template"). For more
information, see Section 2.6.1, "How to Extract Variable Information from the Request URI
(@PathParam)."
@QueryParam
Extract information from the query portion of the request URI to initialize the value of a
method parameter. For more information, see Section 2.6.2, "How to Extract Request
Parameters (@QueryParam)."
2.6.1 How to Extract Variable Information from the Request URI (@PathParam)
Add the javax.ws.rs.PathParam annotation to the method parameter of a resource to
extract the variable information from the request URI and initialize the value of the
method parameter. You can define a default value for the variable value using the
@DefaultValue annotation, as described in Section 2.6.3, "How to Define the
DefaultValue (@DefaultValue)."
In Example 23, the @PathParam annotation assigns the value of the username variable
that is defined as part of the URI path by the @Path annotation to the userName method
parameter.
Example 212
Extracting Variable Information From the Request URI
import
import
import
import
javax.ws.rs.GET;
javax.ws.rs.Path;
javax.ws.rs.Produces;
javax.ws.rs.PathParam;

@Path("/users")
. . .
@GET
@Path("/{username}")
@Produces("text/xml")
public String getUser(@PathParam("username") String userName) {
...
}
}
2.6.2 How to Extract Request Parameters (@QueryParam)

Add the javax.ws.rs.QueryParam annotation to the method parameter of a resource
to extract information from the query portion of the request URI and initialize the
value of the method parameter.
The type of the annotated method parameter can be any of the following:
Primitive type (int, char, byte, and so on)
User-defined type
Constructor that accepts a single String argument
Static method named valueOf or fromString that accepts a single String argument
(for example, integer.valueOf(String))
List<T>, Set<T>, or SortedSet<T>
If the @QueryParam annotation is specified but the associated query parameter is not
present in the request, then the parameter value will set as an empty collection for
List, Set or SortedSet, the Java-defined default for primitive types, and NULL for all
other object types. Alternatively, you can define a default value for the parameter
using the @DefaultValue annotation, as described in Section 2.6.3, "How to Define the
DefaultValue (@DefaultValue)."
For more information, see the @QueryParam annotation in the Java EE 7 Specification
APIs.
In Example 213, if the step query parameter exists in the query component of the
request URI, the value will be assigned to the step method parameter as an integer
value. If the value cannot be parsed as an integer value, then a 400 (Client Error)
response is returned. If the step query parameter does not exist in the query
component of the request URI, then the value is set to NULL.
Example 213
Extracting Request Parameters (@QueryParam)
import javax.ws.rs.QueryParam;
...
@Path("smooth")
@GET
public Response smooth(@QueryParam("step") int step)
{ ... }
}
2.6.3 How to Define the DefaultValue (@DefaultValue)

Add the javax.ws.rs.DefaultValue annotation to define the default value of the
request metadata that is bound using one of the following annotations: @CookieParam,
@FormParam, @HeaderParam, @MatrixParam, @PathParam, or @QueryParam. For more
information, see the @DefaultValue annotation in the Java EE 7 Specification APIs.
In Example 214, if the step query parameter does not exist in the query component of
the request URI, the default value of 2 will be assigned to the step parameter.
Example 214
Defining the Default Value (@DefaultValue)
import javax.ws.rs.QueryParam;
...
@Path("smooth")
@GET
public Response smooth(@DefaultValue("2") @QueryParam("step") int step)
{ ... }
}
2.6.4 Enabling the Encoding Parameter Values (@Encoded)

Add the javax.ws.rs.Encoded annotation at the class or method level to enable the
encoding of a parameter value that is bound using one of the following annotations:
@FormParam, @MatrixParam, @PathParam, or @QueryParam. If specified at the class level,
parameters for all methods in the class will be encoded. For more information, see the
@Encoded annotation in the Java EE 7 Specification APIs.
In Example 215, the @Encoded annotation enables the encoding of parameter values
bound using the @PathParam annotation.
Example 215
Encoding Parameter Values
import
import
import
import
import
javax.ws.rs.GET;
javax.ws.rs.Path;
javax.ws.rs.PathParam;
javax.ws.rs.Encoded;

@Path("/users")
. . .
@GET
@Path("/{username}")
@Produces("text/xml")
@Encoded
public String getUser(@PathParam("username") String userName) {
...
}
}
2.7 Building Custom Response Messages

By default, JAX-RS responds to HTTP requests using the default response codes
defined in the HTTP specification, such as 200 OK for a successful GET request and 201
CREATED for a successful PUT request.
In some cases, you may want to customize the response codes returned or include
additional metadata information in the response. For example, you might want to
include the Location header to specify the URI to the newly created resource. You can
modify the response message returned using the javax.ws.rs.core.Response class.
An application can extend the Response class directly or use one of the static Response
methods, defined in Table 25, to create a
javax.ws.rs.core.Response.ResponseBuilder instance and build the Response
instance. For more information, see the Response methods in the Java EE 7 Specification
APIs.
Table 25
Creating a Response Instance Using the ResponseBuilder Class
Method
Description
created()
Creates a new ResponseBuilder instance and sets the Location header to the
specified value.
fromResponse()
Creates a new ResponseBuilder instance and copies an existing response.
noContent()
Creates a new ResponseBuilder instance and defines an empty response.
notAcceptable()
Creates a new ResponseBuilder instance and defines a unacceptable response.
notModified()
Creates a new ResponseBuilder instance and returns a not-modified status.
ok()
Creates a new ResponseBuilder instance and returns an OK status.
seeOther()
Creates a new ResponseBuilder instance for a redirection.
serverError()
Creates a new ResponseBuilder instance and returns a server error status.
status()
Creates a new ResponseBuilder instance and returns the specified status.
temporaryRedirect()
Creates a new ResponseBuilder instance for a temporary redirection.
Once you create a ResponseBuilder instance, you can call the methods defined in
Table 26 to build a custom response. Then, call the build() method to create the final
Response instance. For more information, see the Response.ResponseBuilder methods
in the Java EE 7 Specification APIs.
Table 26
ResponseBuilder Methods for Building a Custom Response
Method
Description
allow()
Sets the list of allowed methods for the resource.
build()
Creates the Response instance from the current ResponseBuilder instance.
cacheControl()
Sets the cache control.
clone()
Create a copy of the ResponseBuilder to preserve its state.
contentLocation()
Sets the content location.
cookie()
Add cookies to the response.
encoding()
Sets the message entity content encoding.
entity()
Defines the entity.
expires()
Sets the expiration date.
header()
Adds a header to the response.
language()
Sets the language.
lastModified()
Set the last modified date.
link()
Adds a link header.
links()
Adds one or more link headers.
location()
Sets the location.
newInstance()
Creates a new ResponseBuilder instance.
replaceAll()
Replaces all existing headers with the newly supplied headers.
status()
Sets the status.
tag()
Sets an entity tag.
Table 26 (Cont.) ResponseBuilder Methods for Building a Custom Response

Method
Description
type()
Sets the response media type.
variant()
Set representation metadata.
variants()
Add a Vary header that lists the available variants.
Example 216 shows how to build a Response instance using ResponseBuilder. In this
example, the standard status code of 200 OK is returned and the media type of the
response is set to text/html. A call to the build() method creates the final Response
instance.
Example 216
Building a Custom Response
import javax.ws.rs.PathParam;
import javax.ws.rs.core.Response;
import javax.ws.rs.core.ResponseBuilder;
...
@Path("/content")
public class getDocs {
@GET
@Path("{id}")
public Response getHTMLDoc(@PathParm("id") int docId)
{
Document document = ...;
ResponseBuilder response = Response.ok(document);
response.type("text/html");
return response.build();
}
}
If you wish to build an HTTP response using a generic type, to avoid type erasure at
runtime you need to create a javax.ws.rs.core.GenericEntity object to preserve the
generic type. For more information, see the GenericEntity methods in the Java EE 7
Specification APIs.
Example 217 provides an example of how to build an HTTP response using
GenericEntity to preserve the generic type.
Example 217
Building a Custom Response Using a Generic Type
import javax.ws.rs.PathParam;
import javax.ws.rs.core.ResponseBuilder;
javax.ws.rs.core.GenericEntity;
...
@Path("/content")
public class getDocs {
@GET
@Path("{id}")
public Response getHTMLDoc(@PathParm("id") int docId)
{
Document document = ...;
List<String> list = new ArrayList<String>();
Mapping HTTP Request and Response Entity Bodies Using Entity Providers
GenericEntity<List<String>> entity = new GenericEntity<List<String>>(list) {};

...
ResponseBuilder response = Response.ok(document);
response.entity(entity);
return response.build();
}
}
2.8 Mapping HTTP Request and Response Entity Bodies Using Entity
Providers
Table 27 lists the Java types that are supported automatically by HTTP request and
response entity bodies.
Table 27
Java Types Supported for HTTP Request and Response Entity Bodies
Java Type
Supported Media Types
byte[]
All media types (*/*)
java.lang.String
java.io.InputStream
java.io.Reader
java.io.File
javax.activation.DataSource
javax.xml.transform.Source
XML media types (text/xml, application/xml, and

application/*+xml) and JSON media types (application/json,
application/*+json)
javax.xml.bind.JAXBElement and
application-supplied JAXB classes
XML media types (text/xml, application/xml, and

application/*+xml)
MultivaluedMap<String,String>
Form content (application/x-www-form-urlencoded)
StreamingOutput
All media types (*/*), MessageBodyWriter only
If your RESTful web service utilizes a type that is not listed in Table 27, you must
define an entity provider, by implementing one of the interfaces defined in Table 28,
to map HTTP request and response entity bodies to method parameters and return
types.
Accessing the Application Context
Table 28 Entity Providers for Mapping HTTP Request and Response Entity Bodies to Method Parameters
and Return Types
Entity Provider
Description
javax.ws.rs.ext.Message Maps an HTTP request entity body to a method parameter for an HTTP request.
BodyReader
Optionally, you can use the @Consumes annotation to specify the MIME media types
supported for the entity provider, as described in "Customizing Media Types for the
Request and Response Messages" on page 2-10.
For example:
@Consumes("application/x-www-form-urlencoded")
@Provider
public class FormReader implements MessageBodyReader<NameValuePair> { ...
}
javax.ws.rs.ext.Message Maps the return value to an HTTP response entity body for an HTTP response.
Optionally, you can use the @Produces annotation to specify the MIME media types
BodyWriter
supported for the entity provider, as described in "Customizing Media Types for the
Request and Response Messages" on page 2-10.
For example:
@Produces("text/html")
@Provider
public class FormWriter implements
MessageBodyWriter<Hashtable<String, String>> { ... }
Jersey JSON provides a set of JAX-RS MessageBodyReader and

MessageBodyWriter providers distributed with the Jersey JSON
extension modules. For more information, see "JSON" in the Jersey 2.21
User Guide.
Note:
The following code excerpt provides an example of a class that contains a method
(getClass) that returns a custom type, and that requires you to write an entity
provider.
public class Class1
{
public String hello() { return "Hello"; }
public Class2 getClass(String name) { return new Class2(); };
}
public class Class2
{
public Class2() { }
}
2.9 Accessing the Application Context

The javax.ws.rs.core.Context annotation enables you to access information about
the application deployment context and the context of individual requests. Table 29
summarizes the context types that you can access using the @Context annotation. For
more information, see the @Context annotation in the Java EE 7 Specification APIs.
Developing RESTful Web Services
2-19
Building URIs
Table 29
Context Types
Use this context type . . .
To . . .
HttpHeaders
Access HTTP header information.
Providers
Lookup Provider instances based on a set of search criteria.
Request
Determine the best matching representation variant and to evaluate whether the
current state of the resource matches any preconditions defined. For more
information, see Section 2.11, "Using Conditional GETs."
SecurityContext
Access the security context and secure the RESTful web service. For more
information, see Section 5.4, "Securing RESTful Web Services Using
SecurityContext."
UriInfo
Access application and request URI information. For more information, see
Section 2.10, "Building URIs."
2.10 Building URIs

You can use javax.ws.rs.core.UriInfo to access application and request URI
information. Specifically, UriInfo can be used to return the following information:
Deployed application's base URI
Request URI relative to the base URI
Absolute path URI (with or without the query parameters)
Using UriInfo you can return a URI or javax.ws.rs.core.UriBuilder instance.

UriBuilder simplifies the process of building URIs, and can be used to build new or
extend existing URIs.
The UriBuilder methods perform contextual encoding of characters not permitted in
the corresponding URI component based on the following rules:
application/x-www-form-urlencoded media type for query parameters, as

defined in "Forms" in the HTML specification at the following URL:
http://www.w3.org/TR/html4/interact/forms.html#h-17.13.4.1
RFC 3986 for all other components, as defined at the following URL:
http://www.ietf.org/rfc/rfc3986.txt
Example 218 shows how to obtain an instance of UriInfo using @Context and use it
to return an absolute path of the request URI as a UriBuilder instance. Then, using
UriBuilder build a URI for a specific user resource by adding the user ID as a path
segment and store it in an array. In this example, the UriInfo instance is injected into a
class field. This example is excerpted from the bookmark sample, as described in
Section 2.4.1, "About the Jersey Bookmark Sample."
Example 218
Building URIs
import javax.ws.rs.core.UriBuilder;
import javax.ws.rs.core.UriInfo;
import javax.ws.rs.core.Context;
...
@Path("/users/")
public class UsersResource {
@Context UriInfo uriInfo;
...
@Produces("application/json")
public JSONArray getUsersAsJsonArray() {
JSONArray uriArray = new JSONArray();
for (UserEntity userEntity : getUsers()) {
UriBuilder ub = uriInfo.getAbsolutePathBuilder();
URI userUri = ub
.path(userEntity.getUserid())
.build();
uriArray.put(userUri.toASCIIString());
}
return uriArray;
}
}
2.11 Using Conditional GETs

A conditional GET enables you to evaluate one or more preconditions before processing
a GET request. If the preconditions are met, a Not Modified (304) response can be
returned rather than the normal response, potentially reducing bandwidth and
improving server performance.
JAX-RS provides the javax.ws.rs.core.Request contextual interface enabling you to
perform conditional GETs. You call the evaluatePreconditions() method and pass a
javax.ws.rs.core.EntityTag, the last modified timestamp (as a java.util.Date
object), or both. The values are compared to the If-None-Match or If-Not-Modified
headers, respectively, if these headers are sent with the request.
If headers are included with the request and the precondition values match the header
values, then the evaluatePreconditions() methods returns a predefined
ResponseBuilder response with a status code of Not Modified (304). If the
precondition values do no match, the evaluatePreconditions() method returns null
and the normal response is returned, with 200, OK status.
Example 219 shows how to pass the EntityTag to the evaluatePreconditions()
method and build the response based on whether the preconditions are met.
Example 219
...
@Path("/employee/{joiningdate}")
public class Employee {
Date joiningdate;
public Employee(@PathParam("joiningdate") Date joiningdate, @Context Request req,
@Context UriInfo ui) {
this.joiningdate = joiningdate;
...
this.tag = computeEntityTag(ui.getRequestUri());
if (req.getMethod().equals("GET")) {
Response.ResponseBuilder rb = req.evaluatePreconditions(tag);
// Preconditions met
if (rb != null) {
return rb.build();
}
// Preconditions not met
Accessing the WADL
rb = Response.ok();
rb.tag(tag);
return rb.build();
}
}
}
2.12 Accessing the WADL

The Web Application Description Language (WADL) is an XML-based file format that
describes your RESTful web services application. By default, a basic WADL is
generated at runtime and can be accessed from your RESTful web service by issuing a
GET on the /application.wadl resource at the base URI of your RESTful application.
The content type application/vnd.sun.wadl+xml is not
recognized by Microsoft Internet Explorer 8. In this case, you can
download a copy of the WADL to your local file system for viewing.
Note:
For example:
GET http://<path_to_REST_app>/application.wadl
Alternatively, you can use the OPTIONS method to return the WADL for particular
resource.
Example 220 shows an example of a WADL for the simple RESTful web service
shown in Example 21.
Example 220
Example of a WADL
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>

<application xmlns="http://research.sun.com/wadl/2006/10">
<doc xmlns:jersey="http://jersey.dev.java.net/"
jersey:generatedBy="Jersey: 0.10-ea-SNAPSHOT 08/27/2008 08:24 PM"/>
<resources base="http://localhost:9998/">
<resource path="/helloworld">
<method name="GET" id="sayHello">
<response>
<representation mediaType="text/plain"/>
</response>
</method>
</resource>
</resources>
</application>
2.13 More Advanced RESTful Web Service Tasks

For more information about advanced RESTful web service development tasks, such
as integrating JAX-RS with EJB technology and Contexts and Dependency Injection
(CDI) and using JAXB and JSON, see the Jersey 2.21 User Guide.
3
Developing RESTful Web Service Clients
3
This chapter describes how to develop Java EE web service clients that conform to the
Representational State Transfer (REST) architectural style using Jersey 2.x Java API for
RESTful Web Services (JAX-RS) 2.0 reference implementation (RI).
[4]
Note: Support for the Jersey 1.18 (JAX-RS 1.1RI) client APIs are
deprecated in this release of WebLogic Server but are maintained for
backward compatibility. For more information, see "Develop RESTful
Web Service Clients Using Jersey 1.18 (JAX-RS 1.1 RI)" on page A-1.

to use the Jersey 2.x (JAX-RS 2.0 RI) client APIs as described in this
chapter at your earliest convenience.
Summary of Tasks to Develop RESTful Web Service Clients
Example of a RESTful Web Service Client
Invoking a RESTful Web Service from a Standalone Client
3.1 Summary of Tasks to Develop RESTful Web Service Clients

The following table summarizes a subset of the tasks that are required to develop
RESTful web service clients using Jersey 2.x (JAX-RS 2.0 RI).
Table 31
Task
More Information
Create and configure an instance of the

javax.ws.rs.client.Client class.
"Creating and configuring a Client instance" in

Jersey 2.21 User Guide
Target the Web resource.
"Targeting a web resource" in Jersey 2.21 User Guide
Identify resources on WebTarget.
"Identifying resource on WebTarget" in Jersey 2.21

User Guide
Invoke an HTTP request.
"Invoking a HTTP request" in Jersey 2.21 User Guide
For information about developing RESTful web service clients using Oracle
JDeveloper, see "Creating RESTful Web Services and Clients" in Developing Applications
with Oracle JDeveloper.
3-1
Example of a RESTful Web Service Client
3.2 Example of a RESTful Web Service Client

The following provides a simple example of a RESTful web service client that can be
used to call the RESTful web service defined in Example 21, "Simple RESTful Web
Service". In this example:
The Client instance is created and a WebTarget defined.
The resource path is defined to access the Web resource.
The Invocation.Builder is used to send a get request to the resource.
The response is returned as a String value.
Example 31 Simple RESTful Web Service Client Using Jersey 2.x (JAX-RS 2.0 RI)
package samples.helloworld.client;
...
import javax.ws.rs.client.Client;
import javax.ws.rs.client.ClientBuilder;
import javax.ws.rs.client.Invocation;
import javax.ws.rs.client.WebTarget;
import javax.ws.rs.core.MediaType;
public class helloWorldClient{
public static void main(String[] args) {
Client client = ClientBuilder.newClient();
WebTarget target = client.target("http://localhost:7101/restservice");
WebTarget resourceWebTarget;
resourceWebTarget = target.path("resources/helloworld");
Invocation.Builder invocationBuilder;
invocationBuilder = resourceWebTarget.request(
MediaType.TEXT_PLAIN_TYPE);
Response response = invocationBuilder.get();
System.out.println(response.getStatus());
System.out.println(response.readEntity(String.class));
...
}
...
}
For complete details, see "Client API" in Jersey 2.21 User Guide.
3.3 Invoking a RESTful Web Service from a Standalone Client

When invoking a RESTful web service from an environment that does not have Oracle
Fusion Middleware or WebLogic Server installed locally, without the entire set of
Oracle Fusion Middleware or WebLogic Server classes in the CLASSPATH, you can
use the standalone client JAR file when invoking the web service.
The standalone RESTful web service client JAR supports basic JAX-RS client-side
functionality and OWSM security policies.
To use the standalone RESTful web service client JAR file with your client application,
perform the following steps:
1.
Create a Java SE client using your favorite IDE, such as Oracle JDeveloper. For
more information, see "Developing and Securing Web Services and Clients" in
Developing Applications with Oracle JDeveloper.
2.
Copy the file ORACLE_HOME/oracle_

common/modules/clients/com.oracle.jersey.fmw.client.jar from the
computer hosting Oracle Fusion Middleware to the client computer, where
ORACLE_HOME is the directory you specified as Oracle Home when you installed
Oracle Fusion Middleware.
For example, you might copy the file into the directory that contains other classes
used by your client application.
3.
Add the JAR file to your CLASSPATH.

Note: Ensure that your CLASSPATH includes the JAR file that
contains the Ant classes (ant.jar) as a subset are used by the
standalone client JAR files. This JAR file is typically located in the lib
directory of the Ant distribution.
4.
Configure your environment for Oracle Web Services Manager (OWSM) policies.
This step is optional, required only if you are attaching OWSM security policies to
the RESTful web services client.
The configuration steps required vary based on the type of policy being attached.
Examples are provided below. For additional configuration requirements, see
"Configuring Java SE Applications to Use OPSS" in Securing Applications with
Oracle Platform Security Services.
Example: Basic Authentication
For example, to support basic authentication using the oracle/wss_http_token_
client_policy security policy, perform the following steps:
a.
Copy the jps-config-jse.xml and audit-store.xml files from the domain_

home/config/fmwconfig directory, where domain_home is the name and
location of the domain, to a location that is accessible to the RESTful client.
b.
Create a wallet (cwallet.sso) in the same location that you copied the files in
step 2 that defines a map called oracle.wsm.security and the credential key
name that the client application will use (for example, weblogic-csf-key).
The location of the file cwallet.sso is specified in the configuration file
jps-config-jse.xml with the element <serviceInstance>.For more
information, see "Using a Wallet-based Credential Store" in Securing
Applications with Oracle Platform Security Services.
c.
On the Java command line, pass the following property defining the JPS
configuration file copied in step 1:
-Doracle.security.jps.config=<pathToConfigFile>
For more information, see "Scenario 3: Securing a Java SE Application" in

Securing Applications with Oracle Platform Security Services.
Example: SSL
For example, to support SSL policies, perform the following steps:
a.
Copy the jps-config-jse.xml and audit-store.xml files from the domain_

home/config/fmwconfig directory, where domain_home is the name and
location of the domain, to a location that is accessible to the RESTful client.
b.
On the Java command line, pass the following properties defining the JPS
configuration file copied in step 1:
3-3
Define the JPS configuration file copied in step 1:

-Doracle.security.jps.config=<pathToConfigFile>
For more information, see "Scenario 3: Securing a Java SE Application" in

Define the trust store containing the trusted certificates:
-Djavax.net.ssl.trustStore=<trustStore>
For more information, see "Setting Up the WebLogic Server in Case of a Java
SE Application" in "Setting Up a One-Way SSL Connection to the LDAP" in
Define the trust store password:
-Djavax.net.ssl.trustStorePassword=<password>
4
Building, Packaging, and Deploying RESTful
Web Service Applications
4
[5This
]
chapter describes how to package and deploy Java EE web services that conform
to the Representational State Transfer (REST) architectural style using the Jersey 2.x
Java API for RESTful Web Services (JAX-RS) 2.0 reference implementation (RI).
Building RESTful Web Service Applications
Packaging RESTful Web Service Applications
Deploying RESTful Web Service Applications
4.1 Building RESTful Web Service Applications

Build your RESTful web service and client applications using the compilation tools,
such as Apache Ant, Maven, or your favorite IDE, such as Oracle JDeveloper. For more
information, see "Overview of WebLogic Server Application Development" in
Developing Applications for Oracle WebLogic Server. For more information about
JDeveloper, see "Building Java Projects" in Developing Applications with Oracle
JDeveloper.
4.2 Packaging RESTful Web Service Applications

All RESTful web service applications must be packaged as part of a Web application. If
your web service is implemented as an EJB, it must be packaged and deployed within
a WAR.
Table 41 summarizes the specific packaging options available for RESTful web service
applications.
Building, Packaging, and Deploying RESTful Web Service Applications
4-1
Table 41
Packaging Options for RESTful Web Service Applications
Packaging Option
Description
Application subclass
Define a class that extends javax.ws.rs.core.Application to define the components

of a RESTful web service application deployment and provide additional metadata.
You can add a javax.ws.rs.ApplicationPath annotation to the subclass to configure
the servlet context path.
For more information, see Section 4.2.1, "Packaging With an Application Subclass".
Servlet
Update the web.xml deployment descriptor to configure the servlet and mappings.
The method used depends on whether your Web application is using Servlet 3.0 or
earlier. For more information, see Section 4.2.2, "Packaging With a Servlet".
Default resource
If you do not configure the servlet context path in your configuration using either of
the options specified above, the WebLogic Server provides a default RESTful web
service application servlet context path, resources. For more information, see
Section 4.2.3, "Packaging as a Default Resource."
4.2.1 Packaging With an Application Subclass

In this packaging scenario, you create a class that extends
javax.ws.rs.core.Application to define the components of a RESTful web service
application deployment and provides additional metadata. For more information, see
javax.ws.rs.core.Application in the Java EE 7 Specification APIs.
Within the Application subclass, override the getClasses() and getSingletons()
methods, as required, to return the list of RESTful web service resources. A resource is
bound to the Application subclass that returns it.
Note that an error is returned if both methods return the same resource.
Use the javax.ws.rs.ApplicationPath annotation to define the base URI pattern that
gets mapped to the servlet. For more information about how this information is used
in the base URI of the resource, see Section 2.3.3, "What Happens at Runtime: How the
Base URI is Constructed." For more information, see the @ApplicationPath annotation
in the Java EE 7 Specification APIs.
For simple deployments, no web.xml deployment descriptor is required. For more
complex deployments, for example to secure the web service or specify initialization
parameters, you can package a web.xml deployment descriptor with your application,
as described in Section 4.2.2, "Packaging With a Servlet."
Example 41 provides an example of a class that extends
javax.ws.rs.core.Application and uses the @ApplicationPath annotation to define
the base URI of the resource.
Example 41
Example of a Class that Extends javax.ws.rs.core.Application
import javax.ws.rs.core.Application;
javax.ws.rs.ApplicationPath;
...
@ApplicationPath("resources")
public class MyApplication extends Application {
public Set<Class<?>> getClasses() {
Set<Class<?>> s = new HashSet<Class<?>>();
s.add(HelloWorldResource.class);
return s;
}
}
Alternatively, use the following API to scan for root resource and provider classes for a
specified classpath or a set of package names:
org.glassfish.jersey.server.ResourceConfig, as described in "JAX-RS

Application Model" in Jersey 2.21 User Guide
4.2.2 Packaging With a Servlet

The following sections describe how to package the RESTful web service application
with a servlet using the web.xml deployment descriptor, based on whether your Web
application is using Servlet 3.0 or earlier.
Section 4.2.2.1, "How to Package the RESTful Web Service Application with Servlet
3.0"
Section 4.2.2.2, "How to Package the RESTful Web Service Application with Pre-3.0
Servlets"
The web.xml file is located in the WEB-INF directory in the root directory of your
application archive. For more information about the web.xml deployment descriptor,
see "web.xml Deployment Descriptor Elements" in Developing Web Applications,
Servlets, and JSPs for Oracle WebLogic Server.
4.2.2.1 How to Package the RESTful Web Service Application with Servlet 3.0
To package the RESTful Web Service application with Servlet 3.0, update the web.xml
deployment descriptor to define the elements defined in the following sections. The
elements vary depending on whether you include in the package a class that extends
javax.ws.rs.core.Application.
Section 4.2.2.1.1, "Packaging the RESTful Web Service Application Using web.xml
With Application Subclass"
Section 4.2.2.1.2, "Packaging the RESTful Web Service Application Using web.xml
Without Application Subclass"
For more information about any of the elements, see "servlet" in Developing Web
Applications, Servlets, and JSPs for Oracle WebLogic Server.
4.2.2.1.1 Packaging the RESTful Web Service Application Using web.xml With Application
Subclass If a class that extends javax.ws.rs.core.Application is packaged with
web.xml, then define the elements as described in Table 42. For an example, see
Example 42.
Table 42
Packaging the RESTful Web Service Application Using web.xml With Application Subclass
Element
Description
<servlet-name>
Set this element to the fully qualified name of the class that extends
javax.ws.rs.core.Application. You can specify multiple servlet entries to define
multiple Application subclass names.
4-3
Table 42
(Cont.) Packaging the RESTful Web Service Application Using web.xml With Application
Element
Description
<servlet-class>
Not required.
<init-param>
Not required.
<servlet-mapping>
Set as the base URI pattern that gets mapped to the servlet.
If not specified, one of the following values are used, in order of precedence:
@ApplicationPath annotation value defined in the javax.ws.rs.core.Application

subclass. For example:
package test;
@ApplicationPath("res")
public class MyJaxRsApplication extends java.ws.rs.core.Application
...
For more information, see Section 4.2.1, "Packaging With an Application Subclass."
The value resources. This is the default base URI pattern for RESTful web service
applications. For more information, see Section 4.2.3, "Packaging as a Default
Resource."
If both the <servlet-mapping> and @ApplicationPath are specified, the

<servlet-mapping> takes precedence.
For more information about how this information is used in the base URI of the resource,
see Section 2.3.3, "What Happens at Runtime: How the Base URI is Constructed."
The following provides an example of how to update the web.xml file if a class that
extends javax.ws.rs.core.Application is packaged with web.xml.
Example 42
Updating web.xml for Servlet 3.0 If Application Subclass is in Package
<web-app>
<servlet>
<servlet-name>org.foo.rest.MyApplication</servlet-name>
</servlet>
...
<servlet-mapping>
<servlet-name>org.foo.rest.MyApplication</servlet-name>
<url-pattern>/resources</url-pattern>
</servlet-mapping>
...
</web-app>
4.2.2.1.2 Packaging the RESTful Web Service Application Using web.xml Without Application
Subclass If a class that extends javax.ws.rs.core.Application is not packaged with
web.xml, then define the elements as described in Table 43.
Note: In this scenario, you cannot support multiple RESTful web
service applications.
Table 43
Packaging the RESTful Web Service Application Using web.xml Without Application Subclass
Element
Description
<servlet-name>
Set this element to the desired servlet name.
<servlet-class>
Set this element to org.glassfish.jersey.servlet.ServletContainer to delegate all Web

requests to the Jersey servlet.
<init-param>
Not required.
<servlet-mapping>
Set as the base URI pattern that gets mapped to the servlet. If not specified, this value
defaults to resources. For more information, see Section 4.2.3, "Packaging as a Default
Resource."
The following provides an example of how to update the web.xml file if an class that
extends javax.ws.rs.core.Application is not packaged with web.xml.
Example 43
Updating web.xml for Servlet 3.0 If Application Subclass is Not in Package
<web-app>
<servlet>
<servlet-name>Jersey Web Application</servlet-name>
<servlet-class>org.glassfish.jersey.servlet.ServletContainer</servlet-class>
</servlet>
<servlet-mapping>
<url-pattern>/*</url-pattern>
</servlet-mapping>
</web-app>
4.2.2.2 How to Package the RESTful Web Service Application with Pre-3.0 Servlets
Table 44 describes the elements to update in the web.xml deployment descriptor to
package the RESTful web service application with a pre-3.0 servlet.
4-5
Table 44
Packaging the RESTful Web Service Application with Pre-3.0 Servlets
Element
Description
<servlet-name>
<servlet-class>
Set this element to org.glassfish.jersey.servlet.ServletContainer to delegate all Web

requests to the Jersey servlet.
<init-param>
Set this element to define the class that extends the javax.ws.rs.core.Application:
<init-param>
<param-name>
javax.ws.rs.Application
</param-name>
<param-value>
ApplicationSubclassName
</param-value>
</init-param>
Alternatively, you can specify the packages to be scanned for resources and providers, as
follows:
<init-param>
<param-name>
jersey.config.server.provider.packages
</param-name>
<param-value>
project1
</param-value>
</init-param>
<init-param>
<param-name>
jersey.config.server.provider.scanning.recursive
</param-name>
<param-value>
false
</param-value>
</init-param>
<servlet-mapping>

package test;
...
Resource."

The following provides an example of how to update the web.xml file if an class that
Example 44
Updating web.xml for Pre-3.0 Servlets
<web-app>
<servlet>
<init-param>
<param-name>jersey.config.server.provider.packages</param-name>
<param-value>org.foo.myresources,org.bar.otherresources</param-value>
</init-param>
<init-param>
<param-name>jersey.config.server.provider.scanning.recursive</param-name>
<param-value>false</param-value>
</init-param>
...
</servlet>
...
</web-app>
4.2.3 Packaging as a Default Resource

By default, WebLogic Server defines a default RESTful web service application context
path, resources. The default RESTful web service application context path is used if
the following are true:
You did not update the web.xml deployment descriptor to include a Servlet
mapping, as described in Section 4.2.2, "Packaging With a Servlet."
The @ApplicationPath annotation is not defined in the
javax.ws.rs.core.Application subclass, as described in Section 4.2.1, "Packaging
With an Application Subclass."
Note: If a servlet is already registered at the default context path,
then a warning is issued.
For example, if the relative URI of the root resource class for the RESTful web service
application is defined as @Path('/helloworld') and the default RESTful web service
application context path is used, then the RESTful web service application resource
will be available at:
http://<host>:<port>/<contextPath>/resources/helloworld
4.3 Deploying RESTful Web Service Applications

For information about deploying a Web application, see "Understanding WebLogic
Server Deployment" in Deploying Applications to Oracle WebLogic Server.
4-7
5
Securing RESTful Web Services and Clients
5
This chapter describes how to secure Java EE web services that conform to the
Web Services (JAX-RS) reference implementation (RI).
[6]
About RESTful Web Service Security
Securing RESTful Web Services and Clients Using OWSM Policies
Securing RESTful Web Services Using web.xml
Securing RESTful Web Services Using SecurityContext
Securing RESTful Web Services Using Java Security Annotations
5.1 About RESTful Web Service Security

You can secure your RESTful web services using one of the following methods to
support authentication, authorization, or encryption:
Attaching Oracle Web Services Manager (OWSM) policies. See Section 5.2,
"Securing RESTful Web Services and Clients Using OWSM Policies".
Updating the web.xml deployment descriptor to access information about the
authenticated users. See Section 5.3, "Securing RESTful Web Services Using
web.xml".
Using the javax.ws.rs.core.SecurityContext interface to access security-related
information for a request. See Section 5.4, "Securing RESTful Web Services Using
SecurityContext".
Applying annotations to your JAX-RS classes. See Section 5.5, "Securing RESTful
Web Services Using Java Security Annotations".
JDeveloper, see "How to Attach Policies to RESTful Web Services and Clients" in
Developing Applications with Oracle JDeveloper.
5.2 Securing RESTful Web Services and Clients Using OWSM Policies
Only a subset of OWSM security policies are supported for RESTful web services, as
described in "Which OWSM Policies Are Supported for RESTful Web Services" in
Securing Web Services and Managing Policies with Oracle Web Services Manager.
You can attach OWSM security policies to RESTful web services using one of the
following methods:
Securing RESTful Web Services and Clients 5-1
Securing RESTful Web Services Using web.xml
Programmatically, at design time, as described in "Attaching Policies to RESTful

Web Services and Clients at Design Time" in Securing Web Services and Managing
Policies with Oracle Web Services Manager.
Post-deployment, both directly and globally, using:
Fusion Middleware Control, as described in "Attaching Policies Using Fusion

Middleware Control" in Securing Web Services and Managing Policies with Oracle
Web Services Manager.
WLST, as described in "Attaching Policies Using WLST" in Securing Web

Services and Managing Policies with Oracle Web Services Manager.
Example 51 provides an example of using WLST to attach the oracle/http_basic_

auth_over_ssl_service_policy policy to a RESTful service. For more information,
see "Attaching Policies Directly Using WLST" in Securing Web Services and Managing
Policies with Oracle Web Services Manager.
Example 51
Securing RESTful Web Services Using OWSM Policies With WLST
C:\Oracle\Middleware\oracle_common\common\bin> wlst.cmd
...
wls:/offline> connect("weblogic","password","t3://myAdminServer.example.com:7001")
Connecting to t3://myAdminServer.example.com:7001" with userid weblogic ...
Successfully connected to Admin Server "AdminServer" that belongs to domain "my_domain".
Warning: An insecure protocol was used to connect to the
server. To ensure on-the-wire security, the SSL port or
Admin port should be used instead.
wls:/my_domain/serverConfig> beginWSMSession()
Location changed to domainRuntime tree. This is a read-only tree with DomainMBean as the root.
For more help, use help('domainRuntime')
Session started for modification.
wls:/my_domain/serverConfig> selectWSMPolicySubject('weblogic/my_domain/jaxrs_pack', '#jaxrs_
pack.war', 'REST-Resource(Jersey)')
The policy subject is selected for modification.
wls:/my_domain/serverConfig> attachWSMPolicy('oracle/http_basic_auth_over_ssl_service_policy')
Policy reference "oracle/http_basic_auth_over_ssl_service_policy" added.
wls:/my_domain/serverConfig> commitWSMSession()
The policy set for subject "/weblogic/my_domain/jaxrs_pack|#jaxrs_pack.war|REST-Resource(Jersey)"
was saved successfully.
5.3 Securing RESTful Web Services Using web.xml

You secure RESTful web services using the web.xml deployment descriptor as you
would for other Java EE Web applications. For complete details, see:
"Developing Secure Web Applications" in Developing Applications with the WebLogic

Security Service.
"Securing Web Applications" in The Java EE 7 Tutorial
Securing RESTful Web Services Using SecurityContext
For example, to secure your RESTful web service using basic authentication, perform
the following steps:
1.
Define a <security-constraint> for each set of RESTful resources (URIs) that you
plan to protect.
2.
Use the <login-config> element to define the type of authentication you want to
use and the security realm to which the security constraints will be applied.
3.
Define one or more security roles using the <security-role> tag and map them to
the security constraints defined in step 1. For more information, see "security-role"
in Developing Applications with the WebLogic Security Service.
4.
To enable encryption, add the <user-data-constraint> element and set the

<transport-guarantee> subelement to CONFIDENTIAL. For more information, see
"user-data-constraint" in Developing Applications with the WebLogic Security Service.
The following shows an example of how to secure a Jersey 2.x (JAX-RS 2.0) RESTful
web service using basic authentication.
Example 52
Securing RESTful Web Services Using Basic Authentication
<web-app>
<servlet>
<servlet-name>RestServlet</servlet-name>
</servlet>
<servlet-mapping>
<servlet-name>RestServlet</servlet-name>
</servlet-mapping>
<security-constraint>
<web-resource-collection>
<web-resource-name>Orders</web-resource-name>
<url-pattern>/orders</url-pattern>
<http-method>GET</http-method>
<http-method>POST</http-method>
</web-resource-collection>
<auth-constraint>
<role-name>admin</role-name>
</auth-constraint>
</security-constraint>
<login-config>
<auth-method>BASIC</auth-method>
<realm-name>default</realm-name>
</login-config>
<security-role>
<role-name>admin</role-name>
</security-role>
</web-app>
5.4 Securing RESTful Web Services Using SecurityContext

The javax.ws.rs.core.SecurityContext interface provides access to security-related
information for a request. The SecurityContext provides functionality similar to
javax.servlet.http.HttpServletRequest, enabling you to access the following
security-related information:
java.security.Principal object containing the name of the user making the

request.
Authentication type used to secure the resource, such as BASIC_AUTH, FORM_AUTH,

and CLIENT_CERT_AUTH.
Whether the authenticated user is included in a particular role.
Whether the request was made using a secure channel, such as HTTPS.
You access the SecurityContext by injecting an instance into a class field, setter
method, or method parameter using the javax.ws.rs.core.Context annotation.
For more information, see the following in the Java EE 7 Specification APIs:
SecurityContext interface
@Context annotation
Example 53 shows how to inject an instance of SecurityContext into the sc method

parameter using the @Context annotation, and check whether the authorized user is
included in the admin role before returning the response.
Example 53
Securing RESTful Web Service Using SecurityContext
import
import
import
import
import
javax.ws.rs.GET;
javax.ws.rs.Path;
javax.ws.rs.core.SecurityContext;
javax.ws.rs.core.Context;
...
@Path("/stateless")
@Stateless(name = "JaxRSStatelessEJB")
public class StlsEJBApp {
...
@GET
@Produces("text/plain;charset=UTF-8")
@Path("/hello")
public String sayHello(@Context SecurityContext sc) {
if (sc.isUserInRole("admin")) return "Hello World!";
throw new SecurityException("User is unauthorized.");
}
5.5 Securing RESTful Web Services Using Java Security Annotations

The javax.annotation.security package provides annotations, defined in Table 51,
that you can use to secure your RESTful web services.
Table 51
Annotations for Securing RESTful Web Services
Annotation
Description
@DenyAll
Specifies that no security roles are allowed to invoke the specified methods.
@PermitAll
Specifies that all security roles are allowed to invoke the specified methods.
@RolesAllowed
Specifies the list of security roles that are allowed to invoke the methods in the
application.
Before you can use the annotations defined in Table 51, you must register the
roles-allowed feature, as described in "Securing JAX-RS resources with standard
javax.annotation.security annotations" in the Jersey 2.21 User Guide.
Example 54 shows how to define the security roles that are allowed, by default, to
access the methods defined in the helloWorld class. The sayHello method is
annotated with the @RolesAllows annotation to override the default and only allow
users that belong to the ADMIN security role.
Example 54
Securing RESTful Web Service Using Java Security Annotations
import
import
import
import
javax.ws.rs.GET;
javax.ws.rs.Path;
javax.annotation.Security.RolesAllowed;
@RolesAllowed({"ADMIN", "ORG1"})
@GET
@Path("sayHello")
@RolesAllows("ADMIN")
public String sayHello() {
return "Hello World!";
}
}
For more information, see:
"Specifying Authorized Users by Declaring Security Roles" in The Java EE 7 Tutorial
javax.annotation.security Javadoc
6
Testing RESTful Web Services
6
This chapter describes how to test Java EE web services that conform to the
[7]
After you have deployed a Web application that contains a RESTful web service to
WebLogic Server, you can test your application.
Table 61 lists the methods that can be employed to test your RESTful web service.
Table 61
Methods for Testing RESTful Web Services
Method
Description
Enterprise Manager
Fusion Middleware
Control
Use the test interface provided with Enterprise Manager Fusion Middleware Control
to test the RESTful web service resource methods. For more information, see "Testing
a RESTful Web Service" in Securing Web Services and Managing Policies with Oracle Web
Services Manager.
WebLogic Server
Administration Console
Navigate to the Testing tab for your application deployment in the WebLogic Server
Administration Console to validate the application deployment and view the WADL
file. For more information, see "Test RESTful web services" in Oracle WebLogic Server
Administration Console Online Help.
Testing RESTful Web Services
6-1
7
Monitoring RESTful Web Services and Clients
7
[8This
]
chapter describes how to monitor Java EE web services that conform to the
About Monitoring RESTful Web Services

Monitoring RESTful Web Services Using Enterprise Manager Fusion Middleware
Control
Monitoring RESTful Web Services Using the Administration Console
Monitoring RESTful Web Services Using WLST
Enabling the Tracing Feature
Disabling RESTful Web Service Application Monitoring
Enable Monitoring of Synthetic Jersey Resources in a RESTful Web Service

Application
7.1 About Monitoring RESTful Web Services

WebLogic Server provides several run-time MBeans that capture run-time information
and let you monitor run-time statistics for your RESTful web service applications.
Application monitoring is useful when you need to identify the performance hot-spots
in your JAX-RS application, observe execution statistics of particular resources or
listen to application or request lifecycle events.
You can use the methods defined in Table 71 to monitor your RESTful web service
applications.
Monitoring RESTful Web Services and Clients 7-1
Monitoring RESTful Web Services Using Enterprise Manager Fusion Middleware Control
Table 71
Methods for Monitoring RESTful Web Services
Method
Description
Fusion Middleware Control Enterprise Manager
Access run-time information and monitor run-time

statistics, as described in Section 7.2, "Monitoring
RESTful Web Services Using Enterprise Manager Fusion
Middleware Control."
WebLogic Server Administration Console

RESTful Web Services Using the Administration
Console."
WebLogic Scripting Tool (WLST)

RESTful Web Services Using WLST."
Logging filter
Monitor how a request is processed and dispatched to

Jersey JAX-RS RI components, as described in
Section 7.5, "Enabling the Tracing Feature."
In addition to the monitoring methods described in Table 71, Jersey 2.x (JAX-RS 2.0
RI) provides additional monitoring features, including support for event listeners and
statistics monitoring. For more information, see "Monitoring Jersey Applications" in
the Jersey 2.21 User Guide.
Note: RESTful web service monitoring is enabled by default. In some
cases, this may result in increased memory consumption. You can
disable the monitoring feature at the domain level, and at the
application level. For more information, see "Disabling RESTful Web
Service Application Monitoring" on page 7-6.
7.2 Monitoring RESTful Web Services Using Enterprise Manager Fusion

Middleware Control
Using Enterprise Manager Fusion Middleware Control, you can monitor run-time
statistics for your RESTful Applications and resources, such as error and invocation
counts, execution times, and so on. For complete information, see "Monitoring Web
Services" in Administering Web Services.
7.3 Monitoring RESTful Web Services Using the Administration Console

Using the WebLogic Server Administration Console, you can monitor enhanced
runtime statistics for your RESTful applications and resources, including detailed
deployment and configuration data, global execution statistics, and resource and
resource method execution statistics.
To monitor your deployed RESTful web services using the WebLogic Server
Administration Console, follow these steps:
1.
Invoke the WebLogic Server Administration Console in your browser using the
following URL:
http://[host]:[port]/console
where:
host refers to the computer on which WebLogic Server is running.
2.
port refers to the port number on which WebLogic Server is listening (default
value is 7001).
Follow the procedure described in "Monitor RESTful Web Services" in Oracle

WebLogic Server Administration Console Online Help.
7.4 Monitoring RESTful Web Services Using WLST

You can use WLST to monitor the run-time MBeans, defined in Table 72, that capture
run-time information and run-time statistics for your RESTful web service
applications.
Table 72
Run-time MBeans for Monitoring RESTful Web Services
Run-time MBean
Description
ExceptionMapperStatistic Displays monitoring information about the RESTful web service

s
application exception mapper executions. For more information,
see "JaxRsExceptionMapperStatisticsRuntimeMBean" in MBean
Reference for Oracle WebLogic Server.
JaxRsApplication
Displays monitoring information for the RESTful web service

application. For more information, see
"JaxRsApplicationRuntimeBean" in the MBean Reference for
Oracle WebLogic Server.
RequestStatistics
Displays monitoring information about requests executed by the

RESTful web service application. The statistics apply to all
requests handled by the application and are not bound to any
specific resource or resource method. For more information, see
"JaxRsExecutionStatisticsRuntimeMBean" in MBean Reference for
Oracle WebLogic Server
ResourceConfig
Displays monitoring information about the RESTful web service

application resource configuration. For more information, see
"JaxRsResourceConfigTypeRuntimeBean" in the MBean Reference
for Oracle WebLogic Server.
Note: The JaxRsResourceConfigTypeRuntimeBean is deprecated
in this release of WebLogic Server. You should use the
Properties and ApplicationClass attributes of the
JaxRsApplicationRuntimeMBean instead. For more information,
see "JaxRsApplicationRuntimeBean" in the MBean Reference for
ResponseStatistics
Displays monitoring information about responses created by the

RESTful web service application. The statistics apply to all
responses created by the application and are not bound to any
specific resource or resource method. For more information, see
"JaxRsResponseStatisticsRuntimeMBean" in MBean Reference for
RootResources
Displays monitoring information about the RESTful web service

resource. Any object that is managed by a container (such as
EJB) will have application scope. All other resources by default
will have request scope. For more information, see
"JaxRsResourceRuntimeMBean" in the MBean Reference for Oracle
WebLogic Server.
Note: This MBean is deprecated in this release of WebLogic
Server. You should use RootResourcesByClass instead.
Table 72
(Cont.) Run-time MBeans for Monitoring RESTful Web Services
Run-time MBean
Description
RootResourcesByClass
Displays monitoring information for each resource class that is

deployed in the RESTful web service application. One resource
class can serve requests matched to different URIs. The array
contains resource classes that are registered in the resource
model plus resource classes of sub resources returned from sub
resource locators. For more information, see
"JaxRsResourceRuntimeMBean" in the MBean Reference for Oracle
WebLogic Server.
RootResourcesbyURI
Displays monitoring information for each URI that is exposed in

the RESTful web service application. For more information, see
"JaxRsUriRuntimeMBean" in MBean Reference for Oracle WebLogic
Server.
Servlet
Displays monitoring information for the servlet that hosts the

RESTful web service application. For more information, see
"ServletRuntimeMBean" in the MBean Reference for Oracle
WebLogic Server.
To monitor RESTful web services using WLST, perform the steps provided in the
following procedure.
In this procedure, the example steps provided demonstrate how to monitor the
JAX-RS 2.0 Asynchronous Processing sample delivered with the WebLogic Server
Samples Server, described at "Sample Applications and Code Examples" in
Understanding Oracle WebLogic Server
1.
Invoke WLST, as described in "Invoking WLST" in Understanding the WebLogic

Scripting Tool.
For example:
c:\Oracle\oracle_common\common\bin> wlst
2.
Connect to the Administration Server instance, as described in "connect" in WLST

Command Reference for WebLogic Server.
For example:
wls:/offline> connect('weblogic','password','t3://localhost:8001')
3.
Navigate to the server run-time MBean, as described in "serverRuntime" in WLST

Command Reference for WebLogic Server.
For example:
wls:/samples/serverConfig> serverRuntime()
Location changed to serverRuntime tree. This is a read-only tree
with ServerRuntimeMBean as the root.
For more help, use help('serverRuntime')
wls:/samples/serverRuntime>
4.
Navigate to the Web application component runtime MBean.

For example, to navigate to runtime MBean for the application named
jaxrs-async:
wls:/samples/serverRuntime> cd('ApplicationRuntimes/jaxrs-async')
wls:/samples/serverRuntime/ApplicationRuntimes/jaxrs-async>
cd('ComponentRuntimes')
wls:/samples/serverRuntime/ApplicationRuntimes/jaxrs/ComponentRuntimes> cd
('AdminServer_/jaxrs-async')
5.
Navigate to the application run-time MBean for the RESTful web service request
statistics.
For example:
wls:/samples/serverRuntime/ApplicationRuntimes/jaxrs-async/ComponentRuntimes>
cd ('AdminServer_/jaxrs-async'
wls:/samples_
domain/serverRuntime/ApplicationRuntimes/jaxrs-async/ComponentRuntimes/AdminSer
ver_/jaxrs-async>
cd
('JaxRsApplications/examples.javaee7.jaxrs.async.MessageApplication/RequestStat
istics/examples.javaee7.jaxrs.async.MessageApplication_RequestStatistics')
6.
Review the monitoring information displayed for the RESTful web service
application. For more information, see "JaxRsApplicationRuntimeBean" in the
MBean Reference for Oracle WebLogic Server.
For example:
wls:/samples/serverRuntime/ApplicationRuntimes/jaxrs-async/ComponentRuntimes/Ad
minServer_/jaxrs-async
/JaxRsApplications/examples.javaee7.jaxrs.async.MessageApplication/RequestStati
stics
/examples.javaee7.jaxrs.async.MessageApplication_RequestStatistics>
ls()
-r-AvgTimeLast15m
-1
-r-AvgTimeLast15s
-1
-r-AvgTimeLast1h
-1
-r-AvgTimeLast1m
-1
-r-AvgTimeLast1s
-1
-r-AvgTimeTotal
0
-r-MaxTimeLast15m
-1
-r-MaxTimeLast15s
-1
-r-MaxTimeLast1h
-1
-r-MaxTimeLast1m
-1
-r-MaxTimeLast1s
-1
-r-MaxTimeTotal
0
-r-MinTimeLast15m
-1
-r-MinTimeLast15s
-1
-r-MinTimeLast1h
-1
-r-MinTimeLast1m
-1
-r-MinTimeLast1s
-1
-r-MinTimeTotal
0
-r-Name
examples.javaee7.jaxrs.async.MessageApplication_RequestStatisti
cs
-r-RequestCountLast15m
0
-r-RequestCountLast15s
0
-r-RequestCountLast1h
0
-r-RequestCountLast1m
0
-r-RequestCountLast1s
0
-r-RequestCountTotal
0
-r-RequestRateLast15m
0.0
-r-RequestRateLast15s
0.0
-r-RequestRateLast1h
0.0
-r-RequestRateLast1m
0.0
-r-RequestRateLast1s
0.0
-r-RequestRateTotal
0.0
Enabling the Tracing Feature
-r-Type
JaxRsExecutionStatisticsRuntime
stics
/examples.javaee7.jaxrs.async.MessageApplication_RequestStatistics>
7.
Navigate to any of the other run-time MBeans described in Table 72 to view

additional monitoring information.
8.
Exit WLST, as described in "Exiting WLST" in Understanding the WebLogic Scripting

Tool.
For example:
stics
/examples.javaee7.jaxrs.async.MessageApplication_RequestStatistics>exit()
Exiting WebLogic Scripting Tool.
c:\>
7.5 Enabling the Tracing Feature

The Jersey tracing feature provides useful information that describes how a request is
processed and dispatched to Jersey JAX-RS RI components. Trace messages are output
in the same order as they occur, so the numbering is useful to reconstruct the tracing
order.
When enabled, the Jersey 2.x tracing facility collects useful information for individual
requests from all components of the JAX-RS server-side request processing pipeline.
The information collected may provide vital details for troubleshooting your Jersey or
JAX-RS application.
The tracing information for a single request is returned to the requesting client in the
HTTP headers of the response. In addition, the information is logged on the
server-side using a dedicated Java Logger instance.
For more information about enabling the Jersey 2.x tracing facility, see "Tracing
Support" in Jersey 2.21 User Guide.
7.6 Disabling RESTful Web Service Application Monitoring

You can disable monitoring for an individual Jersey 2.x Java API for RESTful Web
Services (JAX-RS) application, or globally for an entire WebLogic domain:
At the application level, you can set a WebLogic Server-specific Jersey 2.x
application property, jersey.config.wls.server.monitoring.enabled. For more
information, see "Disabling Monitoring for a RESTful Web Service Application
Using Jersey Property" on page 7-7.
At both the application level and at the domain level, you can disable monitoring
using a WebLogic Configuration MBean,
WebAppComponentMBean.JaxRsMonitoringDefaultBehavior. For more information,
see "Disabling Monitoring for a RESTful Web Service Application Using WebLogic
Configuration MBean" on page 7-9 and "Disabling RESTful Web Service
Application Monitoring for a WebLogic Domain" on page 7-9

WebLogic Server uses the following algorithm to determine whether monitoring
should be enabled or disabled for each application.
1.
WebLogic Server checks the JAX-RS application property

jersey.config.wls.server.monitoring.enabled.
If it is set for the application, then WebLogic Server uses this value to determine if
monitoring should be enabled or disabled for the application. If this value is not
set, it proceeds to the next step.
2.
WebLogic Server checks the configuration MBean

WebAppComponentMBean.JaxRsMonitoringDefaultBehavior property for the
individual application.
If it is set for the application, then WebLogic Server uses this value to determine if
3.
WebLogic Server checks the configuration MBean

WebAppContainerMBean.JaxRsMonitoringDefaultBehavior property setting for
the domain.
If it is set for the domain, then WebLogic Server uses this value to determine if
4.
WebLogic Server uses the default setting, which is to enable JAX-RS monitoring
for the application if none of the configuration properties in the previous steps
have been set.
7.6.1 Disabling Monitoring for a RESTful Web Service Application Using Jersey
Property
Jersey 2.x supports the following WebLogic Server-specific property that you can use
to disable application monitoring for an individual RESTful web service application:
jersey.config.wls.server.monitoring.enabled
Setting this property to false disables monitoring in the application. You can set this
property programmatically in the JAX-RS application subclass code, or declaratively
via Servlet init parameters specified in the web.xml as shown in the following
examples.
For convenience, the property name is stored in the
weblogic.jaxrs.server.WeblogicServerProperties.MONITORING_ENABLED constant
field.
Example 71 provides an example of how you can disable monitoring
programmatically in a RESTful web service application by extending the JAX-RS
Application class.
Example 71 Disable Application Monitoring Programmatically by Extending the JAX-RS
Application Class
ApplicationPath("/")
public Map<String, Object> getProperties() {
final Map<String, Object> properties = new HashMap<>();
// Disable JAX-RS Application monitoring (and WLS console monitoring) for this
internal application.
properties.put(weblogic.jaxrs.server.WeblogicServerProperties.MONITORING_
ENABLED, false);
return properties;
}
}
Example 72 provides an example of how you can disable monitoring

programmatically in a RESTful web service application by extending the JAX-RS
Jersey ResourceConfig class.
Example 72 Disable Application Monitoring Programmatically by Extending the Jersey
ResourceConfig Class
@ApplicationPath("/")
public class MyApplication extends ResourceConfig {
public MyApplication() {
// ...
// Disable JAX-RS Application monitoring (and WLS console monitoring) for this
internal application.
property(weblogic.jaxrs.server.WeblogicServerProperties.MONITORING_ENABLED,
false);
}
// ...
}
Example 73 provides an example of how you can disable monitoring declaratively

using Servlet init parameters specified in the web.xml.
Example 73 Disable Application Monitoring Declaratively Using Servlet Init Parameters
in web.xml
<?xml version="1.0" encoding="ISO-8859-1"?>
<web-app version="2.5"
xmlns="http://java.sun.com/xml/ns/javaee"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://java.sun.com/xml/ns/javaee
http://java.sun.com/xml/ns/javaee/web-app_2_5.xsd">
<servlet>
<servlet-name>com.examples.MyApplication</servlet-name>
...
<init-param>
<param-name>jersey.config.wls.server.monitoring.enabled</param-name>
<param-value>false</param-value>
</init-param>
...
<load-on-startup>1</load-on-startup>
</servlet>
<servlet-mapping>
</servlet-mapping>
</web-app>
7.6.2 Disabling Monitoring for a RESTful Web Service Application Using WebLogic
Configuration MBean
After you have deployed a RESTful web service application on WebLogic Server, you
can disable monitoring of the application by using WLST, for example, to set the
JaxRsMonitoringDefaultBehavior property to false on its WebAppComponentMBean:
webAppComponentMBean.setJaxRsMonitoringDefaultBehavior("false")
This is a per-application property that is internally used by Jersey/WebLogic
integration code to determine the state of the default monitoring behavior in the
JAX-RS application:
If set to true, monitoring for the JAX-RS application is enabled.
If set to false, monitoring for the JAX-RS application is disabled.
If the property is not set, then the domain-level Web Application Container
property WebAppContainerMBean.isJaxRsMonitoringDefaultBehavior()) is used
as a fall-back.
Note: The value of this application-specific property (if set) overrides
the value of domain-level configuration property.
By default the value is not explicitly set.
7.6.3 Disabling RESTful Web Service Application Monitoring for a WebLogic Domain
Application monitoring is enabled by default for all RESTful web service applications
deployed to a WebLogic domain. It is possible to reverse this default behavior in a
WebLogic domain and disable JAX-RS monitoring for all RESTful web service
applications deployed in the domain (unless overridden by an application-specific
configuration) by setting the JaxRsMonitoringDefaultBehavior property on
WebAppContainerMBean to false:
WebAppContainerMBean.setJaxRsMonitoringDefaultBehavior("false")
This Web Application Container property is a domain-level property used by
Jersey/WebLogic integration code to determine the behavior of monitoring in JAX-RS
applications at the domain level:
If set to true (or not set), then JAX-RS monitoring is enabled (if not overridden by
properties set directly in an application). By default this property is not set
explicitly and monitoring is enabled.
If set to false, then monitoring for all JAX-RS applications is disabled by default
for the given domain.
Note: You can override this domain-level setting in each JAX-RS
application by setting similar properties,
WebAppComponentMBean#isJaxRsMonitoringDefaultBehavior()), at
the application level. For more information, see "Disabling Monitoring
for a RESTful Web Service Application Using WebLogic Configuration
MBean" on page 7-9.
You can update the WebAppContainerMBean.JaxRsMonitoringDefaultBehavior

property for the domain using WLST commands before starting the domain, or before
deploying any applications, as shown in Example 74.
Enable Monitoring of Synthetic Jersey Resources in a RESTful Web Service Application
Example 74 provides a sample WLST script that disables JAX-RS monitoring for the
entire domain by default.
Example 74 Sample WLST Script for Disabling JAX-RS Monitoring at Domain Level
connect(<user>, <password>)
edit()
startEdit()
cd("WebAppContainer/<domain_name>/")
cmo.setJaxRsMonitoringDefaultBehavior(false)
activate()
You must restart the domain after you disable monitoring to

ensure that all previously deployed applications are redeployed with
the new setting.
Note:
[Example 75 shows a section of the resulting domain configuration document at

DOMAIN_NAME/config/config.xml after you have changed the
jax-rs-monitoring-default-behavior setting to false.
Example 75 config.xml file with JAX-RS Monitoring Disabled at the Domain Level
<?xml version='1.0' encoding='UTF-8'?>
<domain ...>
<name>mydomain</name>
...
<web-app-container>
<jax-rs-monitoring-default-behavior>false
</jax-rs-monitoring-default-behavior>
</web-app-container>
...
</domain>
Note: Although it is possible to do so, Oracle does not recommend

editing the config.xml file directly. For more information, see
"Domain Configuration Files" in Understanding Domain Configuration
for Oracle WebLogic Server
7.7 Enable Monitoring of Synthetic Jersey Resources in a RESTful Web

Service Application
When a RESTful web service application is deployed on WebLogic Server, the Jersey
runtime (to satisfy JAX-RS specification requirements) introspects all the application
resources and eventually extends the resource model of the application with
additional synthetic resources and/or resource methods. For example, synthetic
resources and resource methods are added to support:
Resources exposing the WADL for the entire JAX-RS application, as well as a
partial WADL for any deployed resource.
OPTIONS method handlers for each resource or resource method of the JAX-RS
application.
HEAD method handlers for each resource or resource method of the JAX-RS
application.
Depending on the application, it is possible that quite a lot of additional synthetic

resources may get added to a deployed application. For performance reasons,
WebLogic Server, by default, does not expose runtime MBeans for these extended
synthetic resources and resource methods.
You can, however, display information about these additional synthetic resources in
the WebLogic Server Administration Console by setting the following Jersey
2.x/JAX-RS application property to true:
jersey.config.wls.server.monitoring.extended.enabled
You can set this property programmatically in the JAX-RS application subclass code, or
declaratively via Servlet init parameters specified in the web.xml as shown in the
following examples.
For convenience, the property name is stored in the
weblogic.jaxrs.server.WeblogicServerProperties.MONITORING_EXTENDED_ENABLED
constant field.
Example 76 provides an example of how you can enable monitoring for synthetic
resources programmatically in a JAX-RS application by extending the JAX-RS
Application class.
Example 76 Enable Synthetic Monitoring Programmatically by Extending the JAX-RS
Application Class
public Map<String, Object> getProperties() {
final Map<String, Object> properties = new HashMap<>();
// Expose MBeans for extended JAX-RS resources and resource methods
properties.put(weblogic.jaxrs.server.WeblogicServerProperties.MONITORING_
EXTENDED_ENABLED, true);
return properties;
}
}
Example 77 provides an example of how you can enable monitoring of synthetic

resources programmatically in a JAX-RS/Jersey application by extending the JAX-RS
Jersey ResourceConfig class.
Example 77 Enable Synthetic Monitoring Programmatically by Extending the Jersey
ResourceConfig Class
public class MyApplication extends ResourceConfig {
public MyApplication() {
// ...
// Expose MBeans for extended JAX-RS resources and resource methods
property(weblogic.jaxrs.server.WeblogicServerProperties.MONITORING_EXTENDED_
ENABLED, true);
}
// ...
}
Monitoring RESTful Web Services and Clients
7-11
Example 78 provides an example of how you can enable monitoring of synthetic

resources declaratively using Servlet init parameters specified in the web.xml.
Example 78 Enable Synthetic Monitoring Declaratively Using Servlet Init Parameters in
web.xml
<?xml version="1.0" encoding="ISO-8859-1"?>
<web-app version="2.5"
xmlns="http://java.sun.com/xml/ns/javaee"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://java.sun.com/xml/ns/javaee
http://java.sun.com/xml/ns/javaee/web-app_2_5.xsd">
<servlet>
...
<init-param>
<param-name>jersey.config.wls.server.monitoring.extended.enabled</param-name>
<param-value>true</param-value>
</init-param>
...
<load-on-startup>1</load-on-startup>
</servlet>
<servlet-mapping>
</servlet-mapping>
</web-app>
8
Using Server-Sent Events in WebLogic Server
8
This chapter explains how to use server-sent events in WebLogic Server. Support for
server-sent events in WebLogic Server is provided through the integration of the Jersey
2.x library. The Jersey 2.x library provides the Reference Implementation (RI) of
JSR-339 (JAX-RS 2.0: Java API for RESTful Web Services).
[9]
Overview of Server-Sent Events (SSE)
Understanding the WebLogic Server-Sent Events API
Sample Applications for Server-Sent Events
8.1 Overview of Server-Sent Events (SSE)

Server-sent events enable servers to push data to Web pages over standard HTTP or
HTTPS through a uni-directional client-server connection. In the server-sent events
communication model, the browser client establishes the initial connection, and the
server provides the data and sends it to the client. For general information about
server-sent events, see the Server-Sent Events W3C Candidate Recommendation.
Server-sent events are part of the HTML 5 specification, which also includes
WebSocket technology. Both communication models enable servers to send data to
clients unsolicited. However, server-sent events establish one-way communication
from server to clients, while a WebSocket connection provides a bi-directional,
full-duplex communication channel between servers and clients, promoting user
interaction through two-way communication. The following key differences exist
between WebSocket and server-sent events technologies:
Server-sent events can only push data to the client, while WebSocket technology
can both send and receive data from a client.
The simpler server-sent events communication model is better suited for
server-only updates, while WebSocket technology requires additional
programming for server-only updates.
Server-sent events are sent over standard HTTP and therefore do not require any
special protocol or server implementation to work. WebSocket technology requires
the server to understand the WebSocket protocol to successfully upgrade an HTTP
connection to a WebSocket connection.
For more information about WebSocket technology, see "Using the WebSocket Protocol
in WebLogic Server" in Developing Applications for Oracle WebLogic Server.
Using Server-Sent Events in WebLogic Server 8-1
Understanding the WebLogic Server-Sent Events API
8.2 Understanding the WebLogic Server-Sent Events API

WebLogic Server supports server-sent events through the integration of the Jersey 2.x.
The use of server-sent events through Jersey 2.x is supported only in JAX-RS resources.
For more information about server-sent events in Jersey 2.x, see "Server-Sent Events
(SSE) Support" in the Jersey 2.21 User Guide.
The WebLogic Server Server-Sent Events API is in the package
org.glassfish.jersey.media.sse. For information about the interfaces and classes
included in this package, see the API documentation for
org.glassfish.jersey.media.sse in the Jersey 2.21 API Documentation.
8.3 Sample Applications for Server-Sent Events

Sample applications for server-sent events are available through the Jersey project at
the following locations:
https://github.com/jersey/jersey/tree/master/examples/server-sent-events
https://github.com/jersey/jersey/tree/master/examples/sse-item-store-weba
pp
https://github.com/jersey/jersey/tree/master/examples/sse-twitter-aggrega
tor
A
Compatibility with Earlier Jersey/JAX-RS
Releases
This appendix describes Jersey 1.x (JAX-RS 1.1 RI) features that have been deprecated
or are no longer supported, but have been maintained for backward compatibility.
[10]
This appendix includes the following sections:
Develop RESTful Web Service Clients Using Jersey 1.18 (JAX-RS 1.1 RI)
Support for Jersey 1.18 (JAX-RS 1.1 RI) Deployments Packaged with Pre-3.0
Servlets
A.1 Develop RESTful Web Service Clients Using Jersey 1.18 (JAX-RS 1.1
RI)
Note: Support for the client packages described in this section,
including the com.sun.jersey package, its nested packages, and the
weblogic.jaxrs.api.client package, is deprecated in this release of
WebLogic Server.

to use the JAX-RS 2.0 client APIs at your earliest convenience. For
more information, see Section 3.1, "Summary of Tasks to Develop
RESTful Web Service Clients."
The Jersey 1.x server-side APIs are no longer supported. You should
use the corresponding standard JAX-RS 2.0 or Jersey 2.x server APIs
instead.
The following table summarizes a subset of the tasks that are required to develop
RESTful web service clients. For more information about advanced tasks, see
Section A.1.6, "More Advanced RESTful Web Service Client Tasks."
Compatibility with Earlier Jersey/JAX-RS Releases A-1
Table A1
Task
More Information
Create and configure an instance of the

weblogic.jaxrs.api.client.Client class.
Section A.1.2, "Creating and Configuring a Client

Instance"
Create an instance of the Web resource.
Section A.1.3, "Creating a Web Resource Instance"
Send requests to the resource. For example, HTTP

requests to GET, PUT, POST, and DELETE resource
information.
Section A.1.4, "Sending Requests to the Resource"
Receive responses from the resource.
Section A.1.5, "Receiving a Response from a

Resource"
JDeveloper, see "Creating RESTful Web Services and Clients" in Developing Applications
with Oracle JDeveloper.
A.1.1 Example of a RESTful Web Service Client

The following provides a simple example of a RESTful web service client that can be
used to call the RESTful web service defined in Example 21, "Simple RESTful Web
Service". In this example:
The Client instance is created to access the client API. For more information, see
Section A.1.2, "Creating and Configuring a Client Instance."
The WebResource instance is created to access the Web resource. For more
information, see Section A.1.3, "Creating a Web Resource Instance."
A get request is sent to the resource. For more information, see Section A.1.4,
"Sending Requests to the Resource."
The response is returned as a String value. For more information about receiving
the response, see Section A.1.5, "Receiving a Response from a Resource."
Additional examples are listed in Section 1.5, "Learn More About RESTful Web
Services."
Example A1 Simple RESTful Web Service Client Using Jersey 1.18 (JAX-RS 1.1 RI)
package samples.helloworld.client;
import weblogic.jaxrs.api.client.Client;
import com.sun.jersey.api.client.WebResource;
public class helloWorldClient {
public helloWorldClient() {
super();
}
Client c = Client.create();
WebResource resource =
c.resource("http://localhost:7101/RESTfulService/jersey/helloworld");
String response = resource.get(String.class);
System.out.println(response);
}
}
A-2 Developing and Securing RESTful Web Services for Oracle WebLogic Server
A.1.2 Creating and Configuring a Client Instance

To access the Jersey JAX-RS RI client API, create an instance of the
weblogic.jaxrs.api.client.Client class.
Alternatively, you can create an instance of the
com.sun.jersey.api.client.Client class.
Note:
Optionally, you can pass client configuration properties, defined in Table A2, when
creating the client instance by defining a
com.sun.jersey.api.client.config.ClientConfig and passing the information to
the create method. For more information, see the ClientConfig interface in the
jersey-bundle 1.18 API.
Table A2
RESTful Web Service Client Configuration Properties
Property
Description
PROPERTY_BUFFER_RESPONSE_ENTITY_ON_EXCEPTION
Boolean value that specifies whether the client should

buffer the response entity, if any, and close resources
when a UniformInterfaceException is thrown. This
property defaults to true.
PROPERTY_CHUNKED_ENCODING_SIZE
Integer value that specifies the chunked encoding size.

A value equal to or less than 0 specifies that the default
chunk size should be used. If not set, then chunking will
not be used.
PROPERTY_CONNECT_TIMEOUT
Integer value that specifies the connect timeout interval

in milliseconds. If the property is 0 or not set, then the
interval is set to infinity.
PROPERTY_FOLLOW_REDIRECTS
Boolean value that specifies whether the URL will

redirect automatically to the URI declared in 3xx
responses. This property defaults to true.
PROPERTY_READ_TIMEOUT
Integer value that specifies the read timeout interval in

milliseconds. If the property is 0 or not set, then the
interval is set to infinity.
Example A2 provides an example of how to create a client instance.

Example A2 Creating a Client Instance
...
...
Example A3 provides an example of how to create a client instance and pass

configuration properties to the create method.
Example A3 Creating and Configuring a Client Instance
import com.sun.jersey.api.client.*;
...
ClientConfig cc = new DefaultClientConfig();
cc.getProperties().put(ClientConfig.PROPERTY_FOLLOW_REDIRECTS, true);
Client c = Client.create(cc);
...
Alternatively, you can configure a client instance after the client has been created, by
setting properties on the map returned from the getProperties method or calling a
specific setter method.
Example A4 provides an example of how to configure a client after it has been
created. In this example:
PROPERTY_FOLLOW_REDIRECTS is configured by setting the property on the map

returned from the getProperties method.
PROPERTY_CONNECT_TIMEOUT is configured using the setter method.
Example A4 Configuring a Client Instance After It Has Been Created

...
c.getProperties().put(ClientConfig.PROPERTY_FOLLOW_REDIRECTS, true);
c.setConnectTimeout(3000);
...
Example A5 provides an example of how to configure a client instance to use basic

authentication.
Example A5 Configuring a Client Instance to Use Basic Authentication
import javax.ws.rs.core.MediaType;
import com.sun.jersey.api.client.Client;
import com.sun.jersey.api.client.filter.HTTPBasicAuthFilter;
...
c.addFilter(new HTTPBasicAuthFilter("weblogic", "weblogic1"));
WebResource resource =
c.resource("http://localhost:7001/management/tenant-monitoring/datasources/JDBC%20Data%20Source-0")
;
String response = resource.accept("application/json").get(String.class); //application/xml
// resource.accept(MediaType.APPLICATION_JSON_TYPE).get(String.class);
System.out.println(response);
...
A.1.3 Creating a Web Resource Instance

Before you can issue requests to a RESTful web service, you must create an instance of
com.sun.jersey.api.client.WebResource or
com.sun.jersey.api.client.AsyncWebResource to access the resource specified by
the URI. The WebResource or AsyncWebResource instance inherits the configuration
defined for the client instance. For more information, see the following in the
jersey-bundle 1.18 API:
WebResource
AsyncWebResource
Note: Because clients instances are expensive resources, if you are

creating multiple Web resources, it is recommended that you re-use a
single client instance whenever possible.
Example A6 provides an example of how to create an instance to a Web resource

hosted at http://example.com/helloworld.
Example A6 Creating a Web Resource Instance
...
public static void main(String[] args) {\
...
WebResource resource = c.resource("http://example.com/helloWorld");
...
Example A7 provides an example of how to create an instance to an asynchronous

Web resource hosted at http://example.com/helloworld.
Example A7 Creating an Asynchronous Web Resource Instance
...
public static void main(String[] args) {\
...
AsyncWebResource asyncResource = c.asyncResource("http://example.com/helloWorld");
...
A.1.4 Sending Requests to the Resource

Use the WebResource or AsyncWebResource instance to build requests to the associated
Web resource, as described in the following sections:
Section A.1.4.1, "How to Build Requests"
Section A.1.4.2, "How to Send HTTP Requests"
Section A.1.4.4, "How to Configure the Accept Header"
Section A.1.4.3, "How to Pass Query Parameters"
A.1.4.1 How to Build Requests

Requests to a Web resource are structured using the builder pattern, as defined by the
com.sun.jersey.api.client.RequestBuilder interface. The RequestBuilder
interface is implemented by com.sun.jersey.api.client.WebResource,
com.sun.jersey.api.client.AsyncWebResource, and other resource classes.
You can build a request using the methods defined in Table A3, followed by the
HTTP request method, as described in Section A.1.4.2, "How to Send HTTP Requests."
Examples of how to build a request are provided in the sections that follow.
For more information, see the RequestBuilder methods in the jersey 1.18 bundle API.
Table A3
Building a Request
Method
Description
accept()
Defines the acceptable media types. See Section A.1.4.4, "How to Configure the
Accept Header."
acceptLanguage()
Defines the acceptable languages using the acceptLanguage method.
cookie()
Adds a cookie to be set.
entity()
Configures the request entity. See Section A.1.4.6, "How to Configure the Request
Entity."
header()
Adds an HTTP header and value. See Section A.1.4.4, "How to Configure the Accept
Header."
type()
Configures the media type. See Section A.1.4.6, "How to Configure the Request
Entity."
A.1.4.2 How to Send HTTP Requests

Table A4 list the WebResource and AsyncWebResource methods that can be used to
send HTTP requests.
In the case of AsyncWebResource, a java.util.concurrent.Future<V> object is
returned, which can be used to access the result of the computation later, without
blocking execution. For more information, see the Future<V> interface methods in the
Java Platform, Standard Edition 6 API Specification.
Table A4
WebResource Methods to Send HTTP Requests
Method
Description
get()
Invoke the HTTP GET method to get a representation of the resource.
head()
Invoke the HTTP HEAD method to get the meta-information of the resource.
options()
Invoke the HTTP OPTIONS method to get the HTTP methods that the JAX-RS service
supports.
post()
Invoke the HTTP POST method to create or update the representation of the specified
resource.
put()
Invoke the HTTP PUT method to update the representation of the resource.
delete()
Invoke the HTTP DELETE method to delete the representation of the resource.
If the response has an entity (or representation), then the Java type of the instance
required is declared in the HTTP method.
Example A8 provides an example of how to send an HTTP GET request. In this
example, the response entity is requested to be an instance of String. The response
entity will be de-serialized to a String instance.
Example A8 Sending an HTTP GET Request
...
...
String response = resource.get(String.class);
...
Example A9 provides an example of how to send an HTTP PUT request and put the
entity foo:bar into the Web resource. In this example, the response entity is requested
to be an instance of com.sun.jersey.api.client.ClientResponse.
Example A9 Sending an HTTP PUT Request
import com.sun.jersey.api.client.ClientResponse;
...
...
ClientResponse response = resource.put(ClientResponse.class, "foo:bar");
...
If you wish to send an HTTP request using a generic type, to avoid type erasure at
runtime, you need to create a com.sun.jersey.api.client.GenericType object to
preserve the generic type. For more information, see the GenericType class in
Example A10 provides an example of how to send an HTTP request using a generic
type using GenericType to preserve the generic type.
Example A10 Sending an HTTP GET Request Using a Generic Type
...
...
List<String> list = resource.get(new GenericType<List<String>>() {});
...
A.1.4.3 How to Pass Query Parameters

You can pass query parameters in the GET request by defining a
javax.ws.rs.core.MultivaluedMap and using the queryParams method on the Web
resource to pass the map as part of the HTTP request.
For more information, see the MultivaluedMap interface in Java EE 6 API Specification.
Example A11 provides an example of how to pass parameters in a GET request to a
Web resource hosted at http://example.com/helloworld, resulting in the following
request URI: http://example.com/base?param1=val1&param2=val2
Example A11 Passing Query Parameters
import javax.ws.rs.core.MultivaluedMap;
import javax.ws.rs.core.MultivaluedMapImpl;
...
...
MultivaluedMap queryParams = new MultivaluedMapImpl();
queryParams.add("param1", "val1");
queryParams.add("param2", "val2");
String response = resource.queryParams(queryParams).get(String.class);
...
A.1.4.4 How to Configure the Accept Header

Configure the Accept header for the request using the accept method on the Web
resource.
Example A12 provides an example of how to specify text/plain as the acceptable
MIME media type in a GET request to a Web resource hosted at
http://example.com/helloworld.
Example A12 Configuring the Accept Header
...
...
String response = resource.accept("text/plain").get(String.class);
...
A.1.4.5 How to Add a Custom Header

Add a custom header to the request using the header method on the Web resource.
Example A13 provides an example of how to add a custom header FOO with the value
BAR in a GET request to a Web resource hosted at http://example.com/helloworld.
Example A13 Adding a Custom Header
...
...
String response = resource.header("FOO", "BAR").get(String.class);
...
A.1.4.6 How to Configure the Request Entity

Configure the request entity and type using the entity method on the Web resource.
Alternatively, you can configure the request entity type only using the type method on
the Web resource.
Example A14 provides an example of how to configure a request entity and type.
Example A14 Configuring the Request Entity
...
...
String response = resource.entity(request, MediaType.TEXT_PLAIN_TYPE).get(String.class);
...
Example A15 provides an example of how to configure the request entity media type
only.
Example A15 Configuring the Request Entity Media Type Only
...
...
String response = resource.type(MediaType.TEXT_PLAIN_TYPE).get(String.class);
...
A.1.5 Receiving a Response from a Resource

You define the Java type of the entity (or representation) in the response when you call
the HTTP method, as described in Section A.1.4.2, "How to Send HTTP Requests."
If response metadata is required, declare the Java type
com.sun.jersey.api.client.ClientResponse as the response type. The
ClientResponse type enables you to access status, headers, and entity information.
The following sections describes the response metadata that you can access using the
ClientResponse. For more information, see ClientResponse class in jersey-bundle 1.18
API.
Section A.1.5.1, "How to Access the Status of Request"
Section A.1.5.2, "How to Get the Response Entity"
A.1.5.1 How to Access the Status of Request

Access the status of a client response using the getStatus method on the
ClientResponse object. For a list of valid status codes, see ClientResponse.Status in
Example A16 provides an example of how to access the status code of the response.
Example A16 Accessing the Status of the Request
...
...
ClientResponse response = resource.get(ClientResponse.class);
int status = response.getStatus();
...
A.1.5.2 How to Get the Response Entity

Get the response entity using the getEntity method on the ClientResponse object.
Example A17 provides an example of how to get the response entity.
Example A17 Getting the Response Entity
...
...
ClientResponse response = resource.get(ClientResponse.class);
String entity = response.getEntity(String.class);
...
A.1.6 More Advanced RESTful Web Service Client Tasks

For more information about advanced RESTful web service client tasks, including
those listed below, see the Jersey 1.18 User Guide.
Adding new representation types
Using filters
Enabling security with HTTP(s) URLConnection
A.2 Support for Jersey 1.18 (JAX-RS 1.1 RI) Deployments Packaged with
Pre-3.0 Servlets
For backwards compatibility, deployments that reference the servlet classes shown in
Table A5 are supported. This table describes the elements to update in the web.xml
deployment descriptor to package the RESTful web service application with a pre-3.0
servlet.
Table A5
Packaging the RESTful Web Service Application with Pre-3.0 Servlets
Element
Description
<servlet-name>
Table A5 (Cont.) Packaging the RESTful Web Service Application with Pre-3.0 Servlets
Element
Description
<servlet-class>
Set this element to one of the following classes to delegate all Web requests to the Jersey
servlet:
weblogic.jaxrs.server.portable.servlet.ServletContainer
com.sun.jersey.spi.container.servlet.ServletContainer
Set this element to define the class that extends the javax.ws.rs.core.Application:
<init-param>
<init-param>
<param-name>
javax.ws.rs.Application
</param-name>
<param-value>
ApplicationSubclassName
</param-value>
</init-param>
Alternatively, you can declare the packages in your application, as follows:
<init-param>
<param-name>
com.sun.jersey.config.property.packages
</param-name>
<param-value>
project1
</param-value>
</init-param>
<servlet-mapping>

package test;
...
Resource."

The following provides an example of how to update the web.xml file if a class that
Example A18 Updating web.xml for Pre-3.0 Servlets
<web-app>
<servlet>
<servlet-class>weblogic.jaxrs.server.portable.servlet.ServletContainer</servlet-class>
<init-param>
Compatibility with Earlier Jersey/JAX-RS Releases
A-11
<param-name>com.sun.jersey.config.property.resourceConfigClass</param-name>
<param-value>com.sun.jersey.api.core.PackagesResourceConfig</param-value>
</init-param>
<init-param>
<param-name>com.sun.jersey.config.property.packages</param-name>
<param-value>org.foo.rest;org.bar.rest</param-value>
</init-param>
...
</servlet>
...
</web-app>

Oracle® Fusion Middleware: Developing and Securing Restful Web Services For Oracle Weblogic Server 12C (12.2.1)

Uploaded by

Copyright:

Available Formats

Oracle® Fusion Middleware: Developing and Securing Restful Web Services For Oracle Weblogic Server 12C (12.2.1)

Uploaded by

Document Information

Original Title

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

Oracle® Fusion Middleware: Developing and Securing Restful Web Services For Oracle Weblogic Server 12C (12.2.1)

Uploaded by

Copyright:

Available Formats

[1]

Developing and Securing RESTful Web Services for Oracle

What's New in This Guide ........................................................................................................................ ix

1 Introduction to RESTful Web Services

Introduction to the REST Architectural Style .........................................................................

2 Developing RESTful Web Services

About RESTful Web Service Development............................................................................. 2-1

3 Developing RESTful Web Service Clients

Summary of Tasks to Develop RESTful Web Service Clients .............................................. 3-1

4 Building, Packaging, and Deploying RESTful Web Service Applications

5 Securing RESTful Web Services and Clients

About RESTful Web Service Security ......................................................................................

6 Testing RESTful Web Services

About Monitoring RESTful Web Services ............................................................................... 7-1

8 Using Server-Sent Events in WebLogic Server

Overview of Server-Sent Events (SSE)..................................................................................... 8-1

A Compatibility with Earlier Jersey/JAX-RS Releases

Boldface type indicates graphical user interface elements associated

Italic type indicates book titles, emphasis, or placeholder variables for

Monospace type indicates commands within a paragraph, URLs, code

What's New in This Guide

New and Changed Features for Release 12c (12.2.1)

It is recommended that you update your RESTful client applications

New and Changed Features for Release 12c (12.1.3)

New and Changed Features for Release 12c (12.1.2)

This chapter includes the following sections:

Introduction to the REST Architectural Style

What are RESTful Web Services?

Standards Supported for RESTful Web Service Development on WebLogic Server

Roadmap for Implementing RESTful Web Services

Learn More About RESTful Web Services

1.1 Introduction to the REST Architectural Style

Introduction to RESTful Web Services

What are RESTful Web Services?

Constraints of the REST Architectural Style

Uses a stateless communication protocol, typically Hypertext Transport Protocol

VisibilitySingle request provides the full details of the request.

ReliabilityEases recovery from partial failures.

Enables the caching of client responses. Responses must be identified as cacheable or

1.2 What are RESTful Web Services?

1.3 Standards Supported for RESTful Web Service Development on

JAX-RS 2.0 Rev a

Roadmap for Implementing RESTful Web Services

Notes: Jersey 2.x (JAX-RS 2.0 RI) support is provided by default in

JSON processing and streaming

Key Features in Jersey 2.x (JAX-RS 2.0 RI)

"Client API" in Jersey 2.21 User Guide

Invoke and process requests asynchronously.

Filters and interceptors

"Asynchronous Services and Clients" in the Jersey 2.21 User Guide

"Advanced Features of the Client API" in Java EE 7 Tutorial

1.4 Roadmap for Implementing RESTful Web Services

Introduction to RESTful Web Services

Learn More About RESTful Web Services

Roadmap for Implementing RESTful Web Services and Clients

Develop RESTful web services.

Chapter 2, "Developing RESTful Web Services"

Develop clients to invoke the RESTful web services.

Section 3.1, "Summary of Tasks to Develop