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.