Apache Wink : 2 Apache Wink Building Blocks
This page last changed on Aug 04, 2009 by michael.
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 sectionsService Implemenatation Building Blocks
Client Components Building Blocks
The Apache Wink Runtime
Service Implementation Building Block OverviewAs 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. ResourceA "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. ProvidersA 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.
Entity ProviderAn "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 ProviderContext 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 Exception Mapping ProviderException 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 URI DispatchingDesigning 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. Figure 5: Apache Wink Logic Flow Symphony SDK Logic FlowFigure 5 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 ExampleThroughout this document, various project examples are used in order to describe the functionality and processes that comprise the Apache Wink. Apache Wink Servlet and Request ProcessorFigure 6: Apache Wink Rest Servlet and Request Processor for the Bookmark Services Server and Reqest ProcessorFigure 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 SpaceThe Bookmarks service URI space consists of the following URI space items and detailed descriptions about their context and functionality.
AssetsAssets 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.
AnnotationsTBD URL HandlingThe Apache Wink receives Http requests and then dispatches a wrapped Http request to the appropriate Resource method. Figure 7: URL Request Handling Request HandlingFigure 7 demonstrates the Http Client request path to the URI dispatcher, once the dispatcher receives the request it is then matched according to the Http method, URL and Mime type and finally the Resource registry definition. Http Methods - GET, POST, PUT, DELETE and OPTIONSThe common Http 1.1 methods for the Apache Wink are defined in the following section. This set of methods can be expanded. Method UsageTable 3: Http Methods
Key - X
GETThe 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 aware components. This means that the operation must have no side effects and GET method requests can be re-issued. HEADThe HEAD method is the same as the GET method except for the fact that the HEAD does not contain message body. POSTThe POST method is used for operations that have side effects and cannot be safely repeated. For example, transferring money from one bank account to another has side effects and should not be repeated without explicit approval by the user. PUTThe PUT method requests that the enclosed entity be stored under the supplied Request-URI. If the Request-URI refers to an already existing resource, the enclosed entity should be considered as a modified version of the one residing on the origin server. DELETEThe DELETE method requests that the origin server delete the resource identified by the Request-URI. This method can be overridden on the origin server. OPTIONSThe OPTIONS method represents a request for information about the communication options available on the request/response chain identified by the Request-URI. Basic URL Query ParametersA 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. Query ParametersTable 4: URL Parameters
Combining URL ParametersA single URL can contain more than one URL parameter, example "?alt=text%2Fjavascript &callback=myfunc"(where "%2F" represents escaped "/"). Apache Wink Building Blocks SummaryThe previous section "Service Implementation Building Blocks" outlines the basic precepts and building blocks that comprise the service side of Apache Wink. Apache Wink ExamplesThe following examples applications are used in this "Apache Wink Developer Guide".
Bookmarks ProjectThis developer guide uses the bookmarks example application in order to describe the logic flow process within Apache Wink. HelloWorld ProjectComplete the step-by-step "HelloWorld" tutorial in chapter 3 "Getting Started with Apache Wink" and then follow the installation instructions on page xx, in order to view the "Bookmarks" example application from within the Eclipse IDE. QADefectsThe QADefects example application illustrates the advanced functionality of Apache Wink by implementing most of the features provided by the Apache Wink (Runtime) framework. Client Component Basics OverviewApache Wink interacts with Rest Web-Services. It maps Rest concepts to Java classes and encapsulates underlying Rest related standards and protocols, as well as providing a plug-in mechanism for 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 ClientThe illustration figure 8 shows the basic elements that comprise the client side of Apache Wink. 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 ComponentsApache Wink is comprised of several key elements that together create a simple and convenient framework for the consumption of Rest based web services. RestClientThe 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. ResourceTBD ClientRequestTBD ClientResponseTBD ClientConfigTBD ClientHandlerTBD InputStreamAdapterTBD EntityTypeTBD ApacheHttpClientConfigTBD The Apache Wink RuntimeThe 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 requests targeted for web services, and passes the request and response instances to the Symphony 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. Request ProcessorThe RequestProcessor is the Apache Wink engine, that is initialized by the RestServlet and is populated with an instance of a DeploymentConfiguration. Deployment ConfigurationThe 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. CustomizationThe Deployment Configuration is customized by extending the DeplymentConfiguration class, overriding specific methods and specifying the new class in the web.xml file of the application.
The following table details the customizable methods of the Deployment Configuration class. Deployment ConfigurationTable 5: Deployment Configuration Customizable Methods
Handler ChainsThe handler chain pattern is used by the Wink runtime for implementing the core functionalities.
RegistriesThe 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 RegistryFirgure 10: Resource Registry Architecture The resources registry maintains all of the root resources in the form of Resource Records.
![]() ![]() ![]() ![]() ![]() ![]() ![]() ![]() ![]() |
![]() |
Document generated by Confluence on Aug 09, 2009 05:24 |