Red Hat Training

A Red Hat training course is available for Red Hat JBoss Enterprise Application Platform

Appendix A. Reference Material

A.1. JAX-RS/RESTEasy Annotations

Table A.1. JAX-RS/RESTEasy Annotations

Annotation	Usage
Cache	Set response `Cache-Control` header automatically.
ClientInterceptor	Identifies an interceptor as a client-side interceptor.
ContentEncoding	Meta annotation that specifies a `Content-Encoding` to be applied via the annotated annotation.
Context	Allows you to specify instances of `javax.ws.rs.core.HttpHeaders`, `javax.ws.rs.core.UriInfo`, `javax.ws.rs.core.Request`, `javax.servlet.HttpServletRequest`, `javax.servlet.HttpServletResponse`, and `javax.ws.rs.core.SecurityContext` objects.
CookieParam	Allows you to specify the value of a cookie or object representation of an HTTP request cookie into the method invocation.
DecorateTypes	Must be placed on a `DecoratorProcessor` class to specify the supported types.
Decorator	Meta-annotation to be placed on another annotation that triggers decoration.
DefaultValue	Can be combined with the other `@*Param` annotations to define a default value when the HTTP request item does not exist.
DELETE	An annotation that signifies that the method responds to HTTP `DELETE` requests.
DoNotUseJAXBProvider	Put this on a class or parameter when you do not want the JAXB `MessageBodyReader`/`Writer` used but instead have a more specific provider you want to use to marshal the type.
Encoded	Can be used on a class, method, or param. By default, inject `@PathParam` and `@QueryParams` are decoded. By adding the `@Encoded` annotation, the value of these params are provided in encoded form.
Form	This can be used as a value object for incoming/outgoing request/responses.
Formatted	Format XML output with indentations and newlines. This is a JAXB Decorator.
GET	An annotation that signifies that the method responds to HTTP `GET` requests.
IgnoreMediaTypes	Placed on a type, method, parameter, or field to tell JAXRS not to use JAXB provider for a certain media type
ImageWriterParams	An annotation that a resource class can use to pass parameters to the `IIOImageProvider`.
Mapped	A `JSONConfig`.
MultipartForm	This can be used as a value object for incoming/outgoing request/responses of the multipart/form-data MIME type.
NoCache	Set `Cache-Control` response header of `nocache`.
NoJackson	Placed on class, parameter, field or method when you do not want the Jackson provider to be triggered.
PartType	Must be used in conjunction with Multipart providers when writing out a List or Map as a `multipart/*` type.
Path	This must exist either in the class or resource method. If it exists in both, the relative path to the resource method is a concatenation of the class and method.
PathParam	Allows you to map variable URI path fragments into a method call.
POST	An annotation that signifies that the method responds to HTTP `POST` requests.
Priority	An annotation to indicate what order a class should be used. Uses an integer parameter with a lower value signifying a higher priority.
Provider	Marks a class to be discoverable as a provider by JAX-RS runtime during a provider scanning phase.
PUT	An annotation that signifies that the method responds to HTTP `PUT` requests.
QueryParam	Allows you to map URI query string parameter or URL form encoded parameter to the method invocation.
ServerInterceptor	Identifies an interceptor as a server-side interceptor.
StringParameterUnmarshallerBinder	Meta-annotation to be placed on another annotation that triggers a `StringParameterUnmarshaller` to be applied to a string-based annotation injector.
Stylesheet	Specifies an XML stylesheet header.
Wrapped	Put this on a method or parameter when you want to marshal or unmarshal a collection or array of JAXB objects.
WrappedMap	Put this on a method or parameter when you want to marshal or unmarshal a map of JAXB objects.
XmlHeader	Sets an XML header for the returned document.
XmlNsMap	A `JSONToXml`.
XopWithMultipartRelated	This annotation can be used to process/produce incoming/outgoing XOP messages (packaged as multipart/related) to/from JAXB annotated objects.

A.2. RESTEasy Configuration Parameters

Table A.2. Elements

Option Name	Default Value	Description
resteasy.servlet.mapping.prefix	No default	If the URL-pattern for the Resteasy servlet-mapping is not `/*`.
resteasy.scan	false	Automatically scan `WEB-INF/lib` JARs and `WEB-INF/classes` directory for both `@Provider` and JAX-RS resource classes (`@Path`, `@GET`, `@POST`, etc..) and register them.
resteasy.scan.providers	false	Scan for `@Provider` classes and register them.
resteasy.scan.resources	false	Scan for JAX-RS resource classes.
resteasy.providers	no default	A comma delimited list of fully qualified `@Provider` class names you want to register.
resteasy.use.builtin.providers	true	Whether or not to register default, built-in `@Provider` classes.
resteasy.resources	No default	A comma delimited list of fully qualified JAX-RS resource class names you want to register.
resteasy.jndi.resources	No default	A comma delimited list of JNDI names which reference objects you want to register as JAX-RS resources.
javax.ws.rs.Application	No default	Fully qualified name of `Application` class to bootstrap in a spec portable way.
resteasy.media.type.mappings	No default	Replaces the need for an `Accept` header by mapping file name extensions (like `.xml` or `.txt`) to a media type. Used when the client is unable to use a `Accept` header to choose a representation (i.e. a browser). You configure this in the `WEB-INF/web.xml` file using the `resteasy.media.type.mappings` and `resteasy.language.mappings`.
resteasy.language.mappings	No default	Replaces the need for an `Accept-Language` header by mapping file name extensions (like `.en` or `.fr`) to a language. Used when the client is unable to use a `Accept-Language` header to choose a language (i.e. a browser).
resteasy.document.expand.entity.references	false	Whether to expand external entities or replace them with an empty string. In JBoss EAP, this parameter defaults to `false`, so it replaces them with an empty string.
resteasy.document.secure.processing.feature	true	Impose security constraints in processing `org.w3c.dom.Document` documents and JAXB object representations.
resteasy.document.secure.disableDTDs	true	Prohibit DTDs in `org.w3c.dom.Document` documents and JAXB object representations.
resteasy.wider.request.matching	true	Turn off class-level expression filtering as defined in the JAX-RS specification and instead match based on the full expression of each JAX-RS method.
resteasy.use.container.form.params	true	Use the `HttpServletRequest.getParameterMap()` method to obtain form parameters. Use this switch if you are calling this method within a servlet filter or consuming the input stream within the filter.

Note

These parameters are configured in the WEB-INF/web.xml file.

Important

In a Servlet 3.0 container, the resteasy.scan.* configurations in the web.xml file are ignored, and all JAX-RS annotated components will be automatically scanned.

For example, javax.ws.rs.Application parameter is configured within init-param of the servlet configuration:

<servlet>
    <servlet-name>Resteasy</servlet-name>
    <servlet-class>org.jboss.resteasy.plugins.server.servlet.HttpServletDispatcher</servlet-class>
    <init-param>
        <param-name>javax.ws.rs.Application</param-name>
        <param-value>org.jboss.resteasy.utils.TestApplication</param-value>
    </init-param>
</servlet>

For example, resteasy.document.expand.entity.references is configured within context-param:

<context-param>
    <param-name>resteasy.document.expand.entity.references</param-name>
    <param-value>true</param-value>
</context-param>

Warning

Changing the default values of the following RESTEasy parameters may cause RESTEasy applications to be potentially vulnerable against XXE attacks:

resteasy.document.expand.entity.references
resteasy.document.secure.processing.feature
resteasy.document.secure.disableDTDs

A.3. RESTEasy JavaScript API Parameters

Table A.3. Parameter Properties

Property	Default Value	Description
$entity		The entity to send as a `PUT`, `POST` request.
$contentType		The MIME type of the body entity sent as the `Content-Type` header. Determined by the `@Consumes` annotation.
$accepts	/	The accepted MIME types sent as the `Accept` header. Determined by the `@Provides` annotation.
$callback		Set to a function (`httpCode`, `xmlHttpRequest`, `value`) for an asynchronous call. If not present, the call will be synchronous and return the value.
$apiURL		Set to the base URI of the JAX-RS endpoint, not including the last slash.
$username		If username and password are set, they will be used for credentials for the request.
$password		If username and password are set, they will be used for credentials for the request.

A.4. REST.Request Class Members

Table A.4. REST.Request Class

Member	Description
execute(callback)	Executes the request with all the information set in the current object. The value is passed to the optional argument callback, not returned.
setAccepts(acceptHeader)	Sets the `Accept` request header. Defaults to `/`.
setCredentials(username, password)	Sets the request credentials.
setEntity(entity)	Sets the request entity.
setContentType(contentTypeHeader)	Sets the `Content-Type` request header.
setURI(uri)	Sets the request URI. This should be an absolute URI.
setMethod(method)	Sets the request method. Defaults to `GET`.
setAsync(async)	Controls whether the request should be asynchronous. Defaults to `true`.
addCookie(name, value)	Sets the given cookie in the current document when executing the request. This will be persistent in the browser.
addQueryParameter(name, value)	Adds a query parameter to the URI query part.
addMatrixParameter(name, value)	Adds a matrix parameter (path parameter) to the last path segment of the request URI.
addHeader(name, value)	Adds a request header.
addForm(name, value)	Adds a form.
addFormParameter(name, value)	Adds a form parameter.

A.5. RESTEasy Asynchronous Job Service

The table below details the configurable context-params for the Asynchronous Job Service. These parameters can be configured in the web.xml file.

Table A.5. Configuration Parameters

Parameter	Description
resteasy.async.job.service.max.job.results	Number of job results that can be held in the memory at any one time. Default value is `100`.
resteasy.async.job.service.max.wait	Maximum wait time on a job when a client is querying for it. Default value is `300000`.
resteasy.async.job.service.thread.pool.size	Thread pool size of the background threads that run the job. Default value is `100`.
resteasy.async.job.service.base.path	Sets the base path for the job URIs. Default value is `/asynch/jobs`.

<web-app>
    <context-param>
        <param-name>resteasy.async.job.service.enabled</param-name>
        <param-value>true</param-value>
    </context-param>

    <context-param>
        <param-name>resteasy.async.job.service.max.job.results</param-name>
        <param-value>100</param-value>
    </context-param>
    <context-param>
        <param-name>resteasy.async.job.service.max.wait</param-name>
        <param-value>300000</param-value>
    </context-param>
    <context-param>
        <param-name>resteasy.async.job.service.thread.pool.size</param-name>
        <param-value>100</param-value>
    </context-param>
    <context-param>
        <param-name>resteasy.async.job.service.base.path</param-name>
        <param-value>/asynch/jobs</param-value>
    </context-param>

    <listener>
        <listener-class>
            org.jboss.resteasy.plugins.server.servlet.ResteasyBootstrap
        </listener-class>
    </listener>

    <servlet>
        <servlet-name>Resteasy</servlet-name>
        <servlet-class>
            org.jboss.resteasy.plugins.server.servlet.HttpServletDispatcher
        </servlet-class>
    </servlet>

    <servlet-mapping>
        <servlet-name>Resteasy</servlet-name>
        <url-pattern>/*</url-pattern>
    </servlet-mapping>

</web-app>

A.6. JAX-WS Tools

wsconsume

wsconsume is a command-line tool provided with JBoss EAP that consumes a WSDL and produces portable JAX-WS service and client artifacts.

Usage

The wsconsume tool is located in the EAP_HOME/bin directory and uses the following syntax.

EAP_HOME/bin/wsconsume.sh [options] <wsdl-url>

Note

Use the wsconsume.bat script for Windows.

Example usage:

Generate Java class files from the Example.wsdl WSDL file
```
EAP_HOME/bin/wsconsume.sh Example.wsdl
```
Generate Java source and class files from the Example.wsdl WSDL file
```
EAP_HOME/bin/wsconsume.sh -k Example.wsdl
```
Generate Java source and class files in the my.org package from the Example.wsdl WSDL file
```
EAP_HOME/bin/wsconsume.sh -k -p my.org Example.wsdl
```

Generate Java source and class files using multiple binding files

EAP_HOME/bin/wsconsume.sh -k -b schema-binding1.xsd -b schema-binding2.xsd Example.wsdl

Use the --help argument or see the below table for a listing of all available wsconsume options.

Table A.6. wsconsume Options

Option	Description
-a, --additionalHeaders	Enable processing of implicit SOAP headers
-b, --binding=<file>	One or more JAX-WS or JAXB binding files
-c --catalog=<file>	Oasis XML Catalog file for entity resolution
-d --encoding=<charset>	The charset encoding to use for generated sources
-e, --extension	Enable SOAP 1.2 binding extension
-h, --help	Show this help message
-j --clientjar=<name>	Create a jar file of the generated artifacts for calling the web service
-k, --keep	Keep/Generate Java source
-l, --load-consumer	Load the consumer and exit (debug utility)
-n, --nocompile	Do not compile generated sources
-o, --output=<directory>	The directory to put generated artifacts
-p --package=<name>	The target package for generated source
-q, --quiet	Be somewhat more quiet
-s, --source=<directory>	The directory to put Java source
-t, --target=<2.1\|2.2>	The JAX-WS specification target
-v, --verbose	Show full exception stack traces
-w --wsdlLocation=<loc>	Value to use for `@WebService.wsdlLocation`

wsprovide

wsprovide is a command-line tool provided with JBoss EAP that generates portable JAX-WS artifacts for a service endpoint implementation. It also has the option to generate a WSDL file.

Usage

The wsprovide tool is located in the EAP_HOME/bin directory and uses the following syntax.

EAP_HOME/bin/wsprovide.sh [options] <endpoint class name>

Note

Use the wsprovide.bat script for Windows.

Example usage:

Generate wrapper classes for portable artifacts in the output directory.
```
EAP_HOME/bin/wsprovide.sh -o output my.package.MyEndpoint
```

Generate wrapper classes and WSDL in the output directory.

EAP_HOME/bin/wsprovide.sh -o output -w my.package.MyEndpoint

Generate wrapper classes in the output directory for an endpoint that references other JARs.

EAP_HOME/bin/wsprovide.sh -o output -c myapplication1.jar:myapplication2.jar my.org.MyEndpoint

Use the --help argument or see the below table for a listing of all available wsprovide options.

Table A.7. wsprovide Options

Option	Description
-a, --address=<address>	The generated port soap:address in WSDL
-c, --classpath=<path>	The classpath that contains the endpoint
-e, --extension	Enable SOAP 1.2 binding extension
-h, --help	Show this help message
-k, --keep	Keep/Generate Java source
-l, --load-provider	Load the provider and exit (debug utility)
-o, --output=<directory>	The directory to put generated artifacts
-q, --quiet	Be somewhat more quiet
-r, --resource=<directory>	The directory to put resource artifacts
-s, --source=<directory>	The directory to put Java source
-t, --show-traces	Show full exception stack traces
-w, --wsdl	Enable WSDL file generation

A.7. JAX-WS Common API Reference

Several JAX-WS development concepts are shared between web service endpoints and clients. These include the handler framework, message context, and fault handling.

Handler Framework

The handler framework is implemented by a JAX-WS protocol binding in the runtime of the client and the endpoint, which is the server component. Proxies and Dispatch instances, known collectively as binding providers, each use protocol bindings to bind their abstract functionality to specific protocols.

Client and server-side handlers are organized into an ordered list known as a handler chain. The handlers within a handler chain are invoked each time a message is sent or received. Inbound messages are processed by handlers before the binding provider processes them. Outbound messages are processed by handlers after the binding provider processes them.

Handlers are invoked with a message context which provides methods to access and modify inbound and outbound messages and to manage a set of properties. Message context properties facilitate communication between individual handlers, as well as between handlers and client and service implementations. Different types of handlers are invoked with different types of message contexts.

Logical Handler

Logical handlers only operate on message context properties and message payloads. Logical handlers are protocol-independent and cannot affect protocol-specific parts of a message. Logical handlers implement interface javax.xml.ws.handler.LogicalHandler.

Protocol Handler

Protocol handlers operate on message context properties and protocol-specific messages. Protocol handlers are specific to a particular protocol and may access and change protocol-specific aspects of a message. Protocol handlers implement any interface derived from javax.xml.ws.handler.Handler, except javax.xml.ws.handler.LogicalHandler.

Service Endpoint Handler

On a service endpoint, handlers are defined using the @HandlerChain annotation. The location of the handler chain file can be either an absolute java.net.URL in externalForm or a relative path from the source file or class file.

@WebService
@HandlerChain(file = "jaxws-server-source-handlers.xml")
public class SOAPEndpointSourceImpl {
   ...
}

Service Client Handler

On a JAX-WS client, handlers are defined either by using the @HandlerChain annotation, as in service endpoints, or dynamically, using the JAX-WS API.

Service service = Service.create(wsdlURL, serviceName);
Endpoint port = (Endpoint)service.getPort(Endpoint.class);

BindingProvider bindingProvider = (BindingProvider)port;
List<Handler> handlerChain = new ArrayList<Handler>();
handlerChain.add(new LogHandler());
handlerChain.add(new AuthorizationHandler());
handlerChain.add(new RoutingHandler());
bindingProvider.getBinding().setHandlerChain(handlerChain);

The call to the setHandlerChain method is required.

Message Context

The MessageContext interface is the super interface for all JAX-WS message contexts. It extends Map<String,Object> with additional methods and constants to manage a set of properties that enable handlers in a handler chain to share processing related state. For example, a handler may use the put method to insert a property into the message context. One or more other handlers in the handler chain may subsequently obtain the message via the get method.

Properties are scoped as either APPLICATION or HANDLER. All properties are available to all handlers for an instance of a message exchange pattern (MEP) of a particular endpoint. For instance, if a logical handler puts a property into the message context, that property is also available to any protocol handlers in the chain during the execution of an MEP instance.

Note

An asynchronous Message Exchange Pattern (MEP) allows for sending and receiving messages asynchronously at the HTTP connection level. You can enable it by setting additional properties in the request context.

Properties scoped at the APPLICATION level are also made available to client applications and service endpoint implementations. The defaultscope for a property is HANDLER.

Logical and SOAP messages use different contexts.

Logical Message Context: When logical handlers are invoked, they receive a message context of type LogicalMessageContext. LogicalMessageContext extends MessageContext with methods which obtain and modify the message payload. It does not provide access to the protocol-specific aspects of a message. A protocol binding defines which components of a message are available via a logical message context. A logical handler deployed in a SOAP binding can access the contents of the SOAP body but not the SOAP headers. On the other hand, the XML/HTTP binding defines that a logical handler can access the entire XML payload of a message.
SOAP Message Context: When SOAP handlers are invoked, they receive a SOAPMessageContext. SOAPMessageContext extends MessageContext with methods which obtain and modify the SOAP message payload.

Fault Handling

An application may throw a SOAPFaultException or an application-specific user exception. In the case of the latter, the required fault wrapper beans are generated at runtime if they are not already part of the deployment.

public void throwSoapFaultException() {
   SOAPFactory factory = SOAPFactory.newInstance();
   SOAPFault fault = factory.createFault("this is a fault string!", new QName("http://foo", "FooCode"));
   fault.setFaultActor("mr.actor");
   fault.addDetail().addChildElement("test");
   throw new SOAPFaultException(fault);
}

public void throwApplicationException() throws UserException {
   throw new UserException("validation", 123, "Some validation error");
}

JAX-WS Annotations

The annotations available by the JAX-WS API are defined in JSR-224. These annotations are in the javax.xml.ws package.

The annotations available by the JWS API are defined in JSR-181. These annotations are in the javax.jws package.

Revised on 2018-02-08 10:18:36 EST

Select Your Language

Language:

Language:

Red Hat Training

Appendix A. Reference Material

A.1. JAX-RS/RESTEasy Annotations

A.2. RESTEasy Configuration Parameters

A.3. RESTEasy JavaScript API Parameters

A.4. REST.Request Class Members

A.5. RESTEasy Asynchronous Job Service

A.6. JAX-WS Tools

wsconsume

Usage

wsprovide

Usage

A.7. JAX-WS Common API Reference

Handler Framework

Message Context

Fault Handling

JAX-WS Annotations

Quick Links

Help

Site Info

Related Sites

About

Red Hat legal and privacy links

Red Hat legal and privacy links

Language:

Language and Page Formatting Options

Language:

Red Hat Training

Appendix A. Reference Material

A.1. JAX-RS/RESTEasy Annotations

A.2. RESTEasy Configuration Parameters

A.3. RESTEasy JavaScript API Parameters

A.4. REST.Request Class Members

A.5. RESTEasy Asynchronous Job Service

A.6. JAX-WS Tools

wsconsume

Usage

wsprovide

Usage

A.7. JAX-WS Common API Reference

Handler Framework

Message Context

Fault Handling

JAX-WS Annotations

Quick Links

Help

Site Info

Related Sites

Systems Status

About

Red Hat legal and privacy links

Red Hat legal and privacy links