Apache Wink Building

...

Block Basics

In order to take full advantage of Apache Wink, a basic understanding of the building blocks that comprise it and their functional integration is required. The following sectiondescribes the section provides an introduction to the  basic concepts and building blocks of Apache Wink, version 0.1. In order to gain in-depth understandings of the building blocks refer to the table of contents where these concepts are expanded and addtional example are used to further illustrate the Apache Wink and JAX-RS SDK technologies.

This section contains the following

...

topics:

Service

...

Implementation Building Blocks

• Resource
• Providers
• URI Dispatching
• Assets
• Annotations
• Url URL Handling
• Http MethodsHTTP Methods - GET, POST, PUT, DELETE and OPTIONS
• Basic URL Query URL Query Parameters
• Apache Wink Building Blocks Summary

Client Components Building Blocks

• RestClient Class
• Resource Interface
• ClientRequest Interface
• ClientResponse Interface
• ClientConfig Class
• ClientHandler Interface
• InputStreamAdapter Interface
• OutputStreamAdapter Interface
• EntityType Class
• ApacheHttpClientConfig

The Apache Wink Runtime

• Request Processor
• Deployment Configuration
• Handler ChainChains

...

Service Implementation Building Block Overview

As mentioned in the previous "Apache Wink Introduction" section, Apache Wink 1.0 reflects the design principles of a REST web service. It does so by providing the developer with a set of java classes that enable the implementation of "Resources", "Representations" and the association between them. Wink 1.0 also enables the developer to define the resource URI and the "Uniform methods" that are applicable to the resource.

...

A provider is a class that is annotated with the @Provider annotation and implements one or more interfaces defined by the JAX-RS specification. Providers are not bound to any specific resource. The appropriate provider is automatically selected by the Apache Wink runtime according to the JAX-RS specification. Apache Wink supplies many providers, however, application developers may supply their own which take precedence over any provider in the default runtime.

There are three types of providers defined by the JAX-RS specification:

...

An "Entity Provider" is a class that converts server data into a specific format requested by the client and/or converts a request transmitted by the client into server data. An entity provider can For instance, a String entity provider can turn request entities (message bodies) over the wire into a Java type (java.lang.String). Entity providers can also turn native Java types such as a java.lang.String into an appropriate response entity. An entity provider can be restricted to support a limited set of media types using the @Produces and @Consumes annotations. An entity @javax.ws.rs.Produces and @javax.ws.rs.Consumes annotations. An entity provider is configured to handle a specific server data type by implementing the javax.ws.rs.ext.MessageBodyWriter and/or javax.ws.rs.ext.MessageBodyReader interfaces.

...

Context providers are used to supply contexts to resource classes and other providers by implementing the context javax.ws.rs.ext.ContextResolver interface. For example, if a custom JAXBContext is required to serialize or deserialize JAXB objects, an application can provide a ContextResolver that will return a specific instance of a JAXBContext. Context providers may restrict the media types that they support using the @Produces @javax.ws.rs.Produces annotation.

Figure 3: Context Provider Diagram

...

Exception mapping providers map a checked or runtime exception exceptions into an instance of a javax.ws.rs.core.Response by implementing the javax.ws.rs.ext.ExceptionMapper interface. The Response objects can contain response information such as status codes, HTTP headers, and a response entity (message body). When a resource method throws an exception for which there is an exception mapping provider, the matching provider is used to obtain a Response instanceruntime will try to find a suitable ExceptionMapper to "translate" the exception to an appropriate Response object.

Figure 4: Exception Mapping Provider Diagram

...

Designing an efficient REST web service requires that the application developer understands the resources that comprise the service, how to best identify the resources, and how they relate to one another. Restful

RESTful resources are identified by URIs in most cases related resources have URIs that share common path elements.

...

Figure 5 illustrates the Apache Wink logic flow. The Http HTTP request sent by the client invokes the "Apache Wink Rest REST Servlet". The Rest REST servlet uses the "Request DispatcherProcessor" and the request URI in order to find, match and invoke the correct resource method.

...

Throughout this document, various project examples are used in order to describe the functionality and processes that comprise the Apache Wink.
In order to explain the Rest REST design principles used in the Apache Wink this developer guide refers to the "Bookmark" example project found in the examples folder located in the Apache Wink distribution.

...

Apache Wink Servlet and Request Processor

Figure 6:  Apache Wink Rest REST Servlet and Request Processor for the Bookmark Services

...

Figure 6 shows the Apache Wink servlet and request Processor concept in the context of the application server. In the "Bookmarks" example in figure Figure 6 there are two Resources, the first Resource is assosiated associated with the /mybookmarks URI and manages the bookmarks collection, the second resource is assosiated associated with the /mybookmarks/{bookmark} Resources and manages an individual bookmark within the collection.

The Resources' defined by the web service and managed by Apache Wink are referred to as "URI space". The Resources space is the collection of all URI's that exist in the same context. Figure 6 shows the URI spacew space that contains /mybookmarks and /mybookmarks/{bookmarks}.

...

...

Assets are classes that contain "web service business logic" implemented by the developer. Each Asset is associated with one or more URI. The Apache Wink dispatcher invokes the Asset, which is associated with the URI found in the Http HTTP request.

An Asset class can implement one or more methods, each method is associated with a single Http HTTP method (GET, HEAD, POST, PUT, DELETE etc).  The methods can be associated with a Mime MIME type of a produced representation. Methods that handle Http HTTP verbs of requests with a body (such as PUT, POST) are also associated with the Mime MIME type of the Http HTTP request.
The Asset class can be registered to the Apache Wink using the "Spring context xml" or by using a registration API.

...

Annotations

Annotations are a special text notations, or metadata, added to Java version 1.5. Annotations in Java source code can affect both compilation and runtime behavior of the resulting Java classes.
JAX-RS is implemented by the use of annotations that are defined in the JAX-RS specification. Apache Wink provides a set of additional annotations that enrich the functionality of the JAX-RS enabled application.

...

URL Handling

The Apache Wink receives Http HTTP requests and then dispatches a wrapped Http HTTP request to the appropriate Resource method.
The Http HTTP request is match to the Resource method based on the Http HTTP request parameters, the Resource method definitions and the Mime MIME type.

Figure 7: URL Request Handling

...

Figure 7 demonstrates the Http HTTP Client request path to the URI dispatcher, once the dispatcher receives the request it is then matched according to the Http HTTP method, URL and Mime MIME type and finally the Resource registry definition.

...

...

HTTP Methods - GET, POST, PUT, DELETE and OPTIONS

The common Http HTTP 1.1 methods for the Apache Wink are defined in the following section. This set of methods can be expanded.

Method Usage

Table 3: Http HTTP Methods

...

• Safe - does not affect the server state
• Idempotent - a repeated application of the same method has the same effect as a single application
• Cacheable - a response to a method is cacheable if it meets the requirements for Http cachinHTTP caching
• * -   Responses to this method are not cacheable, unless the response includes an appropriate Cache-Control or Expires header fields. However, the 303 response can be used to direct the user agent to retrieve a cacheable resource.

...

The GET method is used to retrieve information from a specified URI and is assumed to be a safe and repeatable operation by browsers, caches and other Http HTTP aware components. This means that the operation must have no side effects and GET method requests can be re-issued.

...

The POST method submits data to be processed, for example, from an  Html an HTML form, to the identified resource. The data is included in the body of the request. This may result in the creation of a new resource or the updates of existing resources or both.

...

A URL parameter is a name and value pair appended to a URL. The parameter begins with a question mark "?" and takes the form of name=value.
If more than one URL parameter exists, each parameter is separated by an ampersand "&" symbol. URL parameters enable the client to send data as part of the URL to the server.

When a server receives a request and parameters are appended to the URL of the request, the server uses these parameters as if they were sent as part of the request body. There are several predefined URL parameters recognized by the Symphony SDKApache Wink when using Wink providers. The following table lists the parameters commonly used in web service URLs. These special URL parameters are defined in the "RestConstants" class.

...

...

The QADefects example application illustrates the advanced functionality of Apache Wink by implementing most of the features provided by the Apache Wink (Runtime) framework.

...

Apache Wink Client Component Basics Overview

The Apache Wink Client interacts with Rest REST Web-Services. It maps Rest REST concepts to Java classes and encapsulates underlying Rest REST related standards and protocols, as well as providing a plug-in mechanism for RAW Http raw HTTP streaming data manipulation. This mechanism also provides the ability to embed cross application functionality on the client side, such as security, compression and caching.

Figure 8: Apache Wink Client Simplified Breakdown

Apache Wink Client

Figure 8: The illustration figure 8 shows the basic elements that comprise the client side of Apache Wink Client. The Apache Wink exposes several data models for use in the applications business logic. These data models are utilized by the application with the Rest concepts that the client exposes. Apache Wink provides the developer with the ability to implement and embed cross application functionality by implementing a Handler Chain mechanism. The Apache Wink Client communicates with Rest services via the Http protocol.

Client Components

Client utilizes the providers mechanism defined by the JAX-RS specification to perform reading and writing of java objects. The Apache Wink Client is pre-initialized with the same providers that are predefined by the Apache Wink JAX-RS server implementation.

...

Apache Wink Client Components

The Apache Wink Client Apache Wink is comprised of several key elements that together create a simple and convenient framework for the consumption of Rest REST based web services.

RestClient

The client is an abstraction of REST concepts modeled into simple java classes that encapsulate the underlying HTTP protocol, used for the service invocation.

The Apache Wink Client uses the java HttpURLConnection class for the HTTP invocation. The Apache Wink Client also provides a module that utilizes the Apache HTTP Client instead of the default HttpURLConnection class.

The following section provides an overview of the key elements and classes that comprise the Apache Wink Client.

RestClient Class

The RestClient class is the central access point to Apache Wink Client. It provides the user with functionality that enables the creation of new Resource instances. The RestClient provides the user with the RestClient class is the central access point to Apache Wink. It provides the user with functionality that enables the creation of new resources. The RestClient provides the user with the ability to set different configuration parameters and propagated them, to each resource created. Once the resource is created, it can be manipulated by invoking the Http common methods, GET, PUT, POST and DELETE. The default usage of the Apache Wink is to create and reuse the RestClient object within the application.

Resource

TBD

ClientRequest

TBD

ClientResponse

TBD

ClientConfig

TBD

ClientHandler

TBD

InputStreamAdapter

TBD

OutputStreamAdapter

TBD

EntityType

TBD

ApacheHttpClientConfig

custom JAX-RS providers and propagates them to the created resources.

Resource Interface

The Resource interface represents a single web resource located at a specific URL, enabling for the manipulation and retrieval of the resource by the invocation of different HTTP methods on the resource instance. The resource interface is implemented following the Builder design pattern so method calls can be easily aggregated and in order to enable easy construction of requests and setting of the resource properties prior to invocation.

ClientRequest Interface

The ClientRequest interface represents a request issued by invoking any one of the invocation methods on a Resource. An instance of a ClientRequest is created at the beginning of an invocation and passed to all the client handlers defined on the client that was used for the invocation.

ClientResponse Interface

The ClientResponse interface represents an HTTP response that is received after invoking any one of the invocation methods on a Resource. An instance of a ClientResponse is created by the ConnectionHandler at the end of the handler chain, and is returned from every handler on the chain.

ClientConfig Class

The ClientConfig class provides client configuration when instantiating a new RestClient. The ClientConfig is implemented using the Builder design pattern so method calls can be easily aggregated. Custom Providers and client Handlers are set on the ClientConfig instance prior to the creation of the RestClient.

ClientHandler Interface

Client handlers are used to incorporate cross invocation functionality. The ClientHandler interface is implemented by client handlers, and the handle() method is invoked for every request invocation in order to allow the handler to perform custom actions during the request invocation.

InputStreamAdapter Interface

The InputStreamAdapter interface is used to wrap the response input stream with another input stream in order to allow the manipulation of the response entity stream. The adapt() method is called after reading the response status code and response headers, and before returning to the ClientResponse to the handlers on the chain.

OutputStreamAdapter Interface

The OutputStreamAdapter interface is used to wrap the request output stream with another output stream to allow the manipulation of the request entity stream. The adapt() method is called before writing the request headers to allow the adapter to manipulate the request.

EntityType Class

The EntityType is used to specify the class type and the generic type of responses. Typically, an anonymous "EntityType" instance is created in order to specify the response type, as is shown in the following code example:

Resource resource = client.resource(uri);
List<String> list = resource.get(new EntityType<List<String>>() {});

ApacheHttpClientConfig Class

The "ApacheHttpClientConfig" Configuration object configures the Apache Wink Client to use the Apache HttpClient as the underlying HTTP client. The following code snippet, demonstrates the typical usage:

// creates the client that uses Apache DefaultHttpClient as the underlying Http client.
RestClient client = new RestClient(new ApacheHttpClientConfig(new DefaultHttpClient()));

// creates the resource
Resource resource = client.resource("http://myhost:80/my/service");

// invokes a GET method on the resource and receives the response entity as a string
String entity = resource.get(String.class);
...

...

...

The Apache Wink Runtime

The Apache Wink runtime is deployed on a JEE environment and is configured by defining the RestServlet in the web.xml file of the application. This servlet is the entry point of all the Http HTTP requests targeted for web services, and passes the request and response instances to the Symphony Wink engine for processing.

Figure 9: Apache Wink Request Processor Architecture

The diagram illustrates the core components of the Apache Wink runtime. The Wink engine is the RequestProcessor. It builds an instance of a MessageContext with all of the required information for the request and passes it through the engine handler chains. The handler chains are responsible for serving the request, invoking the required resource method and finally generating a response.
In case of an error, the RequestProcessor invokes the Error chain with the generated exception for producing the appropriate response.
The Apache Wink runtime maintains providers and resources in two registries, the "providers registry" and the "resource registry" utilizing them during request processing.

...

The Apache Wink runtime is initialized with an instance of a Deployment Configuration. The Deployment Configuration holds the runtime configuration, including the handler chains, registries, configuration properties.
The Deployment Configuration is initialized with an instance of a JAX-RS Application used for obtaining user resources and providers.

...

Customization of the Handlers Chain

The Deployment Configuration handler chain is customized by extending the DeplymentConfiguration org.apache.wink.server.handlers.HandlersFactory class, overriding specific methods and specifying the new class in the web.xml file of the application.
In order to specify a different Deployment Configuration HandlersFactory class instead of the default Deployment Configurationhandlers, specify an init parameter for a custom properties file to be loaded by the RestServlet. Then, the value of the symphony.deploymentConfiguration RestServlet init parameter wink.handlersFactoryClass property must be set to be as the fully qualified name of the customized configuration classhandlers class in the properties file.

<servlet>
 <servlet-name>restSdkService</servlet-name>
 <servlet-class>
 comorg.hpapache.wink.server.internal.servlet.RestServlet
 </servlet-class>
 <init-param>
 <param-name>wink.deploymentConfiguration<name>propertiesLocation</param-name>
 <param-value>com.hp.example.MyDeploymentConfig<-value>path/to/my-wink-properties.properties</param-value>
 </init-param>
</servlet>

The following table details the customizable methods of the Deployment Configuration class.

Deployment Configuration

Table 5: Deployment Configuration Customizable Methods

In the my-wink-properties properties file:

wink.handlersFactoryClass=org.apache.wink.MyCustomHandlersFactory

See the JavaDoc for the HandlersFactory API.

...

Handler Chains

The handler chain pattern is used by the Wink runtime for implementing the core functionalities.
There are three handler chains utilized by the Wink runtime:

...

...

Registries

The Apache Wink runtime utilizes two registries for maintaining the JAX-RS resources and providers. Both registries maintain their elements in a sorted state according to the JAX-RS specification for increasing performance during request processing. In addition to the JAX-RS specification sorting, Wink supports the prioritization of resources and providers.

Resource Registry

Firgure 10: Resource Registry Architecture

...