In order to take full advantage of Apache Wink 1.0, a basic understanding of the building blocks that comprise it and their functional integration is required. The following chapter describes the basic concepts and building blocks of Wink, version 0.1.

This chapter contains the following sections

Service Implemenatation Building Blocks

• Providers
• URI Dispatching
• Assets
• Annotations
• Url Handling
• Http Methods
• Basic URL Query Parameters
• Apache Wink Building Blocks Summary

Client Components Building Blocks

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

Service Implementation Building Block Overview

As mentioned in the previous chapter, 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.

Resource

A "resource" represents a serviceable component that enables for the retrieval and manipulation of data. A "resource class" is used to implement a resource by defining the "resource methods" that handle requests by implementing the business logic.
A resource is bound or anchored to a URI space by annotating the resource class with the @Path annotation.

Providers

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.
There are three types of providers defined by the JAX-RS specification:

• Entry Providers
• Context Providers
• Exception Mapping Provider

Entity Provider

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 be restricted to support a limited set of media types using the @Produces and @Consumes annotations. An entity provider is configured to handle a specific server data type by implementing the MessageBodyWriter and or MessageBodyReader interfaces.

Figure 2: Entity Provider Diagram

Context Provider

Context providers are used to supply contexts to resource classes and other providers by implementing the context ContextResolver interface. Context providers may restrict the media types that they support using the @Produces annotation.

Figure 3: Context Provider Diagram
TBD (Picture)

Exception Mapping Provider

Exception mapping providers map a checked or runtime exception into an instance of a Response by implementing the ExceptionMapper interface. When a resource method throws an exception for which there is an exception mapping provider, the matching provider is used to obtain a Response instance.

Figure 4: Exception Mapping Provider Diagram
TBD (Picture)

URI Dispatching

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 resources are identified by URIs in most cases related resources have URIs that share common path elements.

Figure 5: Apache Wink Logic Flow

Symphony SDK Logic Flow

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

Bookmarks Example

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 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.
Refer to the code (using an IDE application) in the example in conjunction with the following explanations and illustrations in this developer guide.

Apache Wink Servlet and Request Processor

Figure 6:  Apache Wink 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 6 there are two Resources, the first Resource is assosiated with the /mybookmarks URI and manages the bookmarks collection, the second resource is assosiated 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 that contains /mybookmarks and /mybookmarks/{bookmarks}.

URI Space

The Bookmarks service URI space consists of the following URI space items and detailed descriptions about their context and functionality.
Table 1: URI Management

Assets

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