Simplifying JAX-RS caching with CDI

This post explains (via a simple example) how you can use CDI Producers to make it a little easier to leverage cache control semantics in your RESTful services

The Cache-Control header was added in HTTP 1.1 as a much needed improvement over the Expires header available in HTTP 1.0. RESTful web services can make use of this header in order to scale their applications and make them more efficient e.g. if you can cache a response of a previous request, then you obviously need not make the same request to the server again if you are certain of the fact that your cached data is not stale!

How does JAX-RS help ?

JAX-RS has had support for the Cache-Control header since its initial (1.0) version. The CacheControl class represents the real world Cache-Control HTTP header and provides the ability to configure the header via simple setter methods. More on the CacheControl class in the JAX-RS 2.0 javadocs

 

jaxrs-cache-control

So how to I use the CacheControl class?

Just return a Response object around which you can wrap an instance of the CacheControl class.

Although this is relatively convenient for a single method, repeatedly creating and returning CacheControl objects can get irritating for multiple methods

CDI Producers to the rescue!

CDI Producers can help inject instances of classes which are not technically beans (as per the strict definition) or for classes over which you do not have control as far as decorating them with scopes and qualifiers are concerned.

The idea is to

  • Have a custom annotation (@CacheControlConfig) to define default values for Cache-Control header and allow for flexibility in case you want to override it

  • Just use a CDI Producer to create an instance of the CacheControl class by using the InjectionPoint object (injected with pleasure by CDI !) depending upon the annotation parameters

  • Just inject the CacheControl instance in your REST resource class and use it in your methods

Additional thoughts

  • In this case, the scope of the produced CacheControl instance is @Dependent i.e. it will live and die with the class which has injected it. In this case, the JAX-RS resource itself is RequestScoped (by default) since the JAX-RS container creates a new instance for each client request, hence a new instance of the injected CacheControl instance will be created along with each HTTP request
  • You can also introduce CDI qualifiers to further narrow the scopes and account for corner cases
  • You might think that the same can be achieved using a JAX-RS filter. That is correct. But you would need to set the Cache-Control header manually (within a mutable MultivaluedMap) and the logic will not be flexible enough to account for different Cache-Control configurations for different scenarios

Results of the experiment

Use NetBeans IDE to play with this example (recommended)

initial-request

  • A GET Request to the same URL will not result in an invocation of your server side REST service. The browser will return the cached value.

second-request

Although the code is simple, if you are feeling lazy, you can grab the (maven) project from here and play around

Have fun!

Posted in Java, Java EE | Tagged , , , , , , | 3 Comments

Valid CDI scopes for Session (EJB) beans

CDI enriches the EJB specification (Session beans to be specific) by providing contextual life cycle management. Session beans are not ‘contextual’ instances in general.

If you are comfortable with CDI in general, the idea of ‘being contextual’ should be pretty clear.

Here are the valid permutations and combinations of EJB session beans and corresponding CDI scopes (Application, Session or Request)

  • Stateless beans can only belong to the @Dependent scope i.e. you can either choose to use the @Dependent pseudo-scope explicitly or just flow with the @Stateless annotation in which case the CDI container will pretty much use @Dependent by default (convention).

The CDI container will not let you get away with any other annotation and the end result would be a deployment failure

  • With Singleton beans, @ApplicationScoped is the only valid CDI scope (@Dependent is the default in case you do not use any other explicit CDI scope)

Again, any other scope annotation and the CDI god will crush your WAR/EAR !

  • Stateful EJBs can have any scope – no restrictions whatsoever! (although I do not see too much value in using @ApplicationScoped for Stateful beans – but that’s just me! feel free to chime in case you think otherwise)

Stay safe !
Cheers ;-)

Posted in Java, Java EE | Tagged , , , , , | 2 Comments

14 February is drawing closer… again !!!

Once in a blue moon, I choose to post non-technical ramblings on this blog

14 February is dawning upon us… yet again! And this time, I (like many of you guys) am spoilt for choices. It’s Friday after all! So lighten up and help me figure this one out ;-)

Posted in Uncategorized | Tagged , , | Leave a comment

Integrating CDI and WebSockets

Thought of experimenting with a simple Java EE 7 prototype application involving JAX-RS (REST), WebSockets and CDI.

Note: Don’t want this to be a spoiler – but this post mainly talks about an issue which I faced while trying to use web sockets and REST using CDI as a ‘glue’ (in a Java EE app). The integration did not materialize, but a few lessons learnt nonetheless :-)

The idea was to use a REST end point as a ‘feed’ for a web socket end point which would in turn ‘push’ data to all connected clients

  • JAX-RS end point which receives data (possibly in real time) from other sources as an input to the web socket end point
  • Use CDI Events as the glue b/w JAX-RS and WebSocket end points and ‘fire’ the payload

  • Use a CDI Observer method in the WebSocket endpoint implementation to push data to connected clients

Of course, finer details like performance, async communication etc have not being considered at this point of time. More of an experiment

But is this even possible ?

Here are the steps which I executed

start

  • Fired a HTTP POST request on the REST end point using Postman

fire-rest

 

Boom! A NullPointerException in the Observer method – I waited for a few seconds and then reality hit me!

NPE

 

Root cause (from what I understand)

  • Behavior of WebSocket end points

WebSocket end points are similar to JAX-RS resource classes in the sense that there is one instance of a web socket endpoint class per connected client (at least by default). This is clearly mentioned in the WebSocket specification. As soon as a client (peer) connects, a unique instance is created and one can safely cache the web socket Session object (representation of the peer) as an instance variable. IMO, this a simple and clean programming model

WS-spec

  • But the CDI container had other plans !

As soon as the REST end point fires a CDI event (in response to a POST request), the CDI container creates a different instance of the WebSocket endpoint (the CDI Observer in this case). Why? Because CDI beans are contextual in nature. The application does not control the instances of CDI beans. It just uses them (via @Inject). Its up to the container to create and destroy bean instances and ensure that an appropriate instance is available to beans executing in the same context. How does the container figure out the context though ? It’s via Scopes – Application, Session, Request etc…..

(again, clearly mentioned in the CDI specification)

CDI-spec

So, the gist of the matter is that there is NO instance of the WebSocket endpoint current context – hence a new instance is created by CDI in order to deliver the message. This of course means that the instance variable would point to null and hence the NPE (Duh !)

So the question is . . .

Which CDI scope is to be used for a WebSocket end point ??? I tried @ApplicationScoped, @SessionScoped and @RequestScoped without much luck – still a new instance and a NPE

Any other options ??

  • Defining a Set of Session as static variable will do the trick

But that IMO is a just a hack and not feasible in case one needs to handle client specific state (which can only be handled as instance variables) in the observer method – it’s bound to remain uninitialized

  • Server Sent events ? But at the end of the day, SSE != WebSocket. In case the use case demands server side push ‘only’, one can opt for it. SSE is not a Java EE standard yet – Java EE 8 might make this possible

Solution ?

I am not an expert – but I guess it’s up to the WebSocket spec to provide more clarity on how to leverage it with CDI. Given that CDI is an indispensable part of the Java EE spec, it’s extremely important that it integrates seamlessly with other specifications – specially HTML5-centric specs such as JAX-RS, WebSocket etc

This post by Bruno Borges links to similar issues related to JMS, CDI and WebSocket and how they integrate with each other.

Did I miss something obvious? Do you have any inputs/solutions? Please feel free to chime in ! :-)

The sample code is available on GitHub (in case you want to take a look). I tried this on GlassFish 4.1 and Wildfly 8.2.0

That’s all for now I guess…. :-)

Cheers!

Posted in Java, Java EE | Tagged , , , | 3 Comments

Sneak peek into the JCache API (JSR 107)

This post covers the JCache API at a high level and provides a teaser – just enough for you to (hopefully) start itching about it ;-)

In this post ….

  • JCache overview
  • JCache API, implementations
  • Supported (Java) platforms for JCache API
  • Quick look at Oracle Coherence
  • Fun stuff – Project Headlands (RESTified JCache by Adam Bien) , JCache related talks at Java One 2014, links to resources for learning more about JCache

What is JCache?

JCache (JSR 107) is a standard caching API for Java. It provides an API for applications to be able to create and work with in-memory cache of objects. Benefits are obvious – one does not need to concentrate on the finer details of implementing the Caching and time is better spent on the core business logic of the application.

JCache components

The specification itself is very compact and surprisingly intuitive. The API defines high level components (interfaces) some of which are listed below

  • Caching Provider – used to control Caching Managers and can deal with several of them,
  • Cache Manager – deals with create, read, destroy operations on a Cache
  • Cache – stores entries (the actual data) and exposes CRUD interfaces to deal with the entries
  • Entry – abstraction on top of a key-value pair akin to a java.util.Map
jcache-high-level-components

Hierarchy of JCache API components

 

JCache Implementations

JCache defines the interfaces which of course are implemented by different vendors a.k.a Providers.

From the application point of view, all that’s required is the implementation to be present in the classpath. The API also provides a way to further fine tune the properties specific to your provider via standard mechanisms.

You should be able to track the list of JCache reference implementations from the JCP website link

JCache provider detection

  • JCache provider detection happens automatically when you only have a single JCache provider on the class path
  • You can choose from the below options as well

Java Platform support

  • Compliant with Java SE 6 and above
  • Does not define any details in terms of Java EE integration. This does not mean that it cannot be used in a Java EE environment – it’s just not standardized yet.
  • Could not be plugged into Java EE 7 as a tried and tested standard
  • Candidate for Java EE 8

Project Headlands: Java EE and JCache in tandem

  • By none other than Adam Bien himself !
  • Java EE 7, Java SE 8 and JCache in action
  • Exposes the JCache API via JAX-RS (REST)
  • Uses Hazelcast as the JCache provider
  • Highly recommended !

Oracle Coherence

This post deals with high level stuff w.r.t JCache in general. However, a few lines about Oracle Coherence in general would help put things in perspective

coherence-logo

  • Oracle Coherence is a part of Oracle’s Cloud Application Foundation stack
  • It is primarily an in-memory data grid solution
  • Geared towards making applications more scalable in general
  • What’s important to know is that from version 12.1.3 onwards, Oracle Coherence includes a reference implementation for JCache (more in the next section)

JCache support in Oracle Coherence

  • Support for JCache implies that applications can now use a standard API to access the capabilities of Oracle Coherence
  • This is made possible by Coherence by simply providing an abstraction over its existing interfaces (NamedCache etc). Application deals with a standard interface (JCache API) and the calls to the API are delegated to the existing Coherence core library implementation
  • Support for JCache API also means that one does not need to use Coherence specific APIs in the application resulting in vendor neutral code which equals portability
    How ironic – supporting a standard API and always keeping your competitors in the hunt ;-) But hey! That’s what healthy competition and quality software is all about !
  • Talking of healthy competition – Oracle Coherence does support a host of other features in addition to the standard JCache related capabilities.
  • The Oracle Coherence distribution contains all the libraries for working with the JCache implementation

coherence_lib

  • The service definition file in the coherence-jcache.jar qualifies it as a valid JCache provider implementation

service-definition

 

Curious about Oracle Coherence ?

JCache at Java One 2014

Couple of great talks revolving around JCache at Java One 2014

Hope this was fun :-)

Cheers !

Posted in Java, Java EE, Java SE | Tagged , , | Leave a comment

Stress testing the OIM web (UI) layer

The default configuration in Oracle IDM reserves 20 threads dedicated for serving front end (UI) requests. This basically means that the application server has a pool of 20 threads which it can utilize to serve users who are accessing OIM via the web console (/identity or /sysadmin).

In case of Weblogic, this is how it is configured

oim-ui-thread-conf

What typically happens is

  • User accesses the OIM URL e.g. http://oimhost:14000/identity
  • Browser sends a simple (HTTP) GET request with some added HTTP request headers and other info of course
  • The application server (e.g. Weblogic) picks up a thread from the pool and uses it to process the request
  • OIM responds back and the browser renders the login page and the user is delighted .. well most of the time! ;-)
  • After the request is served, the thread on the application server is sent back to the pool (remember that pool of 20 threads I just mentioned about) and thus it can be reused by another request

I just wanted to play around with this and executed some simple tests via JMeter

Note: This is merely a front end/UI stress testing – not related to business logic

Steps

Well there are a few configurations you would need to setup in JMeter – they are pretty much standard and have nothing to do with OIM in specific

  • Set up a Thread Group (represents users)
  • Configure HTTP requests e.g. configure the OIM URL, context path, port (again – pretty basic)
  • Configure Result viewer – tree or table mode. This is for real time tracking of results

The JMeter configuration (.jmx) file is available for your reference – just import it in JMeter and you should be able to figure out the exact configuration parameters and tweak them if interested

jmeter-test-plan

Testing parameters

I tried testing with various permutations and combinations by changing the Number of Threads and Ramp-Up Period attributes in the Thread Group setup within JMeter

Number of Threads – equivalent to the number of users you want to simulate
Ramp-Up Period (seconds) – equivalent to the time period/range during which you want JMeter to trigger all the requests

e.g. Number of Threads = 100 and Ramp-Up Period = 20 seconds basically means simulating a scenario where 100 users are accessing your application (OIM in this case) over a period of 20 seconds.

  • Attempt 1: Number of Threads = 100 and Ramp-Up Period = 20 seconds
  • Attempt 2: Number of Threads = 200 and Ramp-Up Period = 20 seconds
  • Attempt 3: Number of Threads = 500 and Ramp-Up Period = 20 seconds
  • Attempt 4: Number of Threads = 1000 and Ramp-Up Period = 20 seconds
  • Attempt 5: Number of Threads = 2000 and Ramp-Up Period = 20 seconds

 

thread-group-config

What I was expecting

To be honest, I expected some delay/latency when 2000 threads (potential users) were fired in a space of 20 seconds. Looks like that did not happen.

Actual Result

All in all, the response was quite healthy.

  • Green results i.e. HTTP 200 (OK) response
  • Low latency and load times

result

To be noted

  • This was executed in a personal test VM (running OIM 11g R2 PS2) and hence there was not much load on the system
  • Can’t expect much latency when the server I am connecting to is just a guest VM ;-)

Still, this was fun and it would be interesting to execute the same test on a server which has running processes in the back end e.g scheduler, some access request processes etc.

If the out of the box configuration of 20 threads does not work for your environment, you can change it using the Weblogic Admin Console – rinse and repeat :-)

Until then.. Cheers !

Posted in Oracle Identity Governance, Oracle Identity Manager | Tagged , , , | Leave a comment

Do you really understand @WebService ?

SOAP web services are not cutting edge technology by any means – although it still has it’s place, REST based web services are offering tough competition. Anyway – this is definitely not a REST vs SOAP post !
I have observed a few instances where Java based SOAP web services have been used in an less than ideal manner to say the least. I think this stems from a lack of understanding around some of the basics of JAX-WS (Java EE specification for SOAP based Web Services) in general.

What’s mentioned in this post is pretty basic stuff related to SOAP based web services built using JAX-WS. Some of the points discussed are

  • what’s the life cycle of a @WebService annotated POJO ?
  • is it thread safe? what happens if concurrent client requests are fired at your web service ?

The @WebService annotation

Technically speaking, the @WebService annotation is all you need to turn a POJO into a SOAP endpoint. Not surprisingly enough, that’s all we generally do – annotate our class with @WebService and some other helper annotations like @WebMethod, @WebParam etc, deploy the WAR, fire up SoapUI, run a few tests and bask in glory !

Things you should know about POJOs annotated with @WebService

  • A POJO annotated with @WebService deployed in a WAR is served by the Web Container (this is significant)
  • Life cycle – a single instance of the POJO serves requests from the client. Pretty much like Servlets.
  • Concurrency aspect (thread safety) – they are not thread safe. The same instance of the bean can be concurrently accessed by multiple threads. Although this is not a problem if your service is stateless i.e. does not use instance variables to store state – you might still face scalability issues though (after all, its just one instance !). If your POJO uses instance variables to store state, then you are in big soup and will definitely face issues w.r.t inconsistent behavior resulting from concurrent threads accessing a single instance of your web service class.

Ideally speaking . . .

  • one should make the web services stateless – fire and forget style. Don’t end up storing state inside instance variables
  • if you do choose to use instance variables – make sure that you as a developer, code your web service in a thread safe manner. There are multiple options here, some of which include using the good old synchronized (far from ideal though!), thread safe collections (ConcurrentHashMap) etc
  • best solution IMO – if you are using a Java EE compliant application server (e.g. Weblogic), you should invariably deploy your web services as an EJB (I am not going to dive into the details of EJBs here ! You can refer to my previous posts if interested).
  • What will you gain by that ? (1) EJBs are thread safe by default. You need not worry about coding concurrency and thread safety as a part of your business logic – you get that for free ! (2) EJBs are pooled components – The container caches instances in memory and allocates them to clients as per request. Scalability for free (note – EJB pooling configurations are container specific and each server defines a specific manner in which to achieve this) (3) EJBs are transnational by default – in case you are accessing back end databases as a part of your web service logic, EJBs are ideal (details of transactions are best dealt by a guy who really understands them in depth! I am not going to embarrass myself by trying to act as if I know them end to end)
  • How do I ‘pump-up’ my web service ? (1) Just use the @Stateless annotation – this turns your mere POJO into a full fledged EJB which can now enjoy all the container services (2) deploy your web service not as a WAR, but as an EJB-JAR packed within an EAR. This will ensure that the EJB container catches hold of your POJO and weaves all the magic I have been bragging about!

Testing

I am not a testing expert – but tools like JMeter can make me look smart! Do yourself a favor and user JMeter to ease your SOAP web service testing process. It’s not that hard. Trivial example below

pojo_ws

Client perspective

  • As far as generating stubs from an existing WSDL is concerned, I would definitely opt for the standard capability within Java SE itself. I am simply stating this because this has worked flawlessly for me in the past instead of trying out other implementations like Axis 2 or Apache CXF
  • I don’t mean to undermine them but I don’t see the value in wasting time looking into other stuff when the JDK itself has a well documented standard tool ! Just hop over to JAVA_HOME/bin, look for the wsimport command and get cracking.
  • Most of the IDEs which provide stub generation capability leverage this very tool

This was just a quick rant of sorts..! Hope it made sense

Cheers!

Posted in Java, Java EE, Java SE | Tagged , , , , , , | Leave a comment

MDB != JMS and vice-versa

Basics

  • A Message Driven Bean (further referred to as MDB) is just another EJB like Stateless, Stateful or a Singleton. It’s specified using the @MessageDriven annotation.
  • MDBs are used for asynchronous message processing
  • They are similar to Stateless EJBs since both of them are pooled by the EJB container
  • However they differ from Stateless EJBs since MDBs cannot be directly accessed by a client. Only the container calls them in response to a message sent by the client to an endpoint which the MDB is listening to.

Commonly used pattern for MDB

  • MDBs are generally used along with JMS (Java Message Service API)
  • A MDB is configured to listen to a JMS destination using @ActivationConfigProperty, implements the javax.jms.MessageListener interface and provides the business logic (message processing) in the onMessage method
  • A component sends a Message to the JMS destination (end point). This is not a synchronous process (as already mentioned above). The message firing method returns immediately and the container takes care of calling the MDB configured to listen that particular JMS destination
jms-based-mdb

JMS based MDB

 

MDB myth

  • MDBs are not part of the JMS spec or coupled with JMS by any means – this is a misconception.
  • MDB are pooled beans which can process messages in an async fashion and can listen to any end point including a JMS queue or destination (most generally seen).
  • In fact, this has been the case since EJB 2.1 and is made possible by the JCA (Java Connector Architecture) spec

What’s JCA ?

  • On a high level, JCA enables Java EE servers to interact with external systems e.g. legacy enterprise information sources etc via a standard SPI (not dealing with intricate JCA details here)
  • One can use the JCA standard interfaces to build a Resource Adapter (RAR file) for a specific system
  • JCA provides contracts for two-way communication (inbound and outbound) b/w the Java EE container and the external system – the implementation for which needs to be present withing the Resource Adapter itself
jca-architecture

Courtesy: JCA Specification document

 

How does JCA enable the concept of Generic MDBs ?

  • JCA defines MDB specific features
  • Just like in the case of a JMS based MDB, a JCA based MDB also needs to implement an interface and define activation properties (both are specific to the JCA Resource Adapter implementation)
  • The external system sends a message which the Resource Adapter accepts via its implementation of the inbound JCA contract and this message is relayed to an internal endpoint (this is again specific to the JCA adapter implementation)
  • The MDB registered to this endpoint kicks in an executes the business logic on the received message
jca-based-mdb

JCA based MDB

 

End result

An external system sending messages to a Java EE container using a standard interface (JCA) while the JCA implementation takes care of delivering it to the appropriate endpoint which further delivers it to the registered MDB

Thing to notice is that this is completely portable across Java EE servers since, EJB spec vendors have to support JCA based MDBs.

Update

Thanks to @henk for reminding me to link to some of the awesome content which David Blevins had posted few years back with regards to this topic.

So here you go… Must read stuff

Further reading

Posted in Java, Java EE | Tagged , , , , , , | 1 Comment

Where can I run EJBs ?

EJBs are built for more than just a Java EE application server. They can also execute in a Java EE Web Profile container or plain Java SE environment (Java SE ! yeah – Easy Java Beans !).

EJB Lite

  • Required to support only a subset of the features which are provided by the full EJB specification – a lightweight version of the same
  • A Java EE Web Profile certified container has to support the EJB Lite spec

Embedded Container

  • Embedded = in-memory
  • Executes in a JVM (plain Java SE environment) e.g. just as a part of bigger Java SE, JavaFX or a Swing application
  • Required to support all the features within the EJB Lite spec.
  • e.g – Open EJB

Application Client Container

  • Technically not an EJB container
  • Executes in a Java SE environment but it has some Java EE capabilities as well
  • Because of it’s Java EE related features, it can be used to talk to remotely deployed EJBs using DI (@EJB) or JNDI calls

EC and ACC are not the same

  • An Embedded Container provides a run time to host EJBs themselves
  • Application Client Containers are meant to host clients of remote EJBs apart from providing the ability to consume other services deployed on remote Java EE servers e.g. interaction with JMS destinations etc.
Posted in Java, Java EE | Tagged , , , , , | 1 Comment

JAX-RS 2.0 : Server side Processing Pipeline

The inspiration for this post was the Processing Pipeline section in the JAX-RS 2.0 specification doc (Appendix C). I like it because of the fact that it provides a nice snapshot of all the modules in JAX-RS – in the form of a ready to gulp capsule !

Blog_JAX-RS_Processing_Pipeline

Courtesy – JAX-RS 2.0 Specification Document

So I thought of using this diagram to provide a brief overview of the different JAX-RS components and how they orchestrate with each other.

What’s covered ?

  • Filters (Request and Response)
  • Method matching
  • Injection
  • Interceptors (Request and Response)
  • Entity Providers (Request and Response)

Note: what’s discussed here is the server side processing pipeline i.e. the sequence of actions which are triggered after the client sends an HTTP request (GET, POST, PUT etc)

It all begins when the client (browser or custom REST client) sends an HTTP request to your awesome RESTful service!

Request Filters (chain)

req-filters

The client request is handled by JAX-RS Filters. They are applicable on both the server and client side (we are going to look at server side filters – both request and response based)

  • Filters are optional components and you can write one by simply implementing the ContainerRequestFilter interface. They need to be annotated using @Provider annotation for automatic detection by the JAX-RS run time

  • One can mutate the instance of ContainerRequestContext and change attributes like headers, cookies, URI etc. Filters do not allow you to access the HTTP request body/message payload (that’s something which Interceptors can do)
  • Can be used to implement logging, authentication etc
  • If the filter implementation class needs to be executed before the resource method matching, use the @PreMatching annotation on the implementation class.
  • Filters can be bound to ALL JAX-RS methods (globally) or selectively by using @NamedBinding annotation or an implementation of the DynamicFeature interface
  • The @Priority annotation can be used to determine the order of execution of multiple filters – a sequential chain.

Method matching

After (successful) filter execution, the JAX-RS run time initiates the resource method matching process

  • The exact method to be invoked is based on the algorithm outlined by the specification (although JAX-RS providers are not bound by it)
  • It’s determined by a combination of below mentioned annotations
  • @GET, @PUT, @POST, @DELETE etc – these are the annotations which should match up to the actual HTTP operation (the mapping of the annotation to the HTTP verb is rather obvious)
  • @Path – its value (relative to the context root) is used to map the request URI e.g. /tweeters/all
  • @Consumes – its values should match the Content-Type header value sent in the HTTP request
  • @Produces – its values should match the Accept header value sent in the HTTP request

HTTP components injection

After the method matching is complete, the required HTTP components get injected into JAX-RS Resource classes (if configured) by the the JAX-RS run time. All we need to do is use the appropriate annotation

HTTP URI parameters

Other HTTP components

JAX-RS makes it easy to access (inject) HTTP request components like headers, cookies and even HTTP form data

  • @HeaderParam – extracts headers of a request. You can also use @Context annotation to inject an instance of HttpHeaders
  • @CookieParam – used to inject HTTP cookies from a HTTP request

  • @FormParam – can help inject values from attributes sent via a HTML Form using the HTTP POST request

  • @BeanParam – Can help use all the above injection related annotations on the instance variables of a custom domain class rather than using these to inject values into individual method parameters

Request Interceptors (chain)

req-interceptors-entityproviders

Interceptors are applicable on both the server and client side (we are going to look at server side interceptors only – both request and response based)

  • Interceptors help allow mutation of the HTTP request payload before it is processed
  • Request Interceptors are invoked only when a MessageBodyReader (see next topic) implementation is registered with the JAX-RS run time.
  • Interceptors for incoming server requests are handled by implementations of the ReaderInterceptor interface and need to be annotated using @Provider annotation for automatic detection by the JAX-RS run time

  • The ReaderInterceptorContext instance is passed by the JAX-RS run time and it has access to the HTTP body in the form of java.io.InputStream
  • Interceptors can be bound to ALL JAX-RS methods (globally) or selectively by using @NamedBinding annotation or an implementation of the DynamicFeature interface
  • Interceptors can be chained and prioritized (using @Priority) and calling the proceed method of the ReaderInterceptorContext automatically invokes the next interceptor in the chain or the MessageBodyReader implementation itself
  • A ReaderInterceptor acts as a wrapper around the MessageBodyReader (invokes it internally)

Entity Providers (converting HTTP request payload to Java type)

Entity Providers help in conversion of HTTP message payload to its appropriate Java type (for injection into the method parameters of JAX-RS resource classes) and vice versa

  • The conversion of HTTP request payload to its corresponding Java type is done by a concrete class implementing the MessageBodyReader interface
  • The readFrom method of the MessageBodyReader implementation is where the action takes place. The JAX-RS run time passes in all the contextual information including the payload itself (in the form of an InputStream) which can then be introspected and converted into the appropriate Java type.

  • JAX-RS spec mandates that an implementation should contain out-of-of-the-box implementations of MessageBodyReader interface for certain Java types like String, InputStream, File etc

Response Filter (chain)

resp-filters

Response Filters are similar to their Request-centric counterpart discussed previously.

  • Response Filters are optional components and you can write one by simply implementing the ContainerResponseFilter interface.
  • These type of filters are used to modify the response headers, add cookies etc. One can mutate the instance of ContainerResponseContext and change attributes like to achieve this. Filters do not allow you to access the HTTP response body/message payload (that’s something which Interceptors can do)
  • They need to be annotated using @Provider annotation for automatic detection by the JAX-RS run time

  • Filters can be bound to ALL JAX-RS methods (globally) or selectively by using @NamedBinding annotation or an implementation of the DynamicFeature interface
  • The @Priority annotation can be used to determine the order of execution of multiple filters – a sequential chain.

Response Interceptors (chain)

resp-interceptors-entityproviders

  • They are invoked only when a MessageBodyWriter (see next topic) is registered to handle outgoing HTTP payload
  • Interceptors for outgoing server responses are handled by implementations of the class WriterInterceptor and need to be annotated using @Provider annotation for automatic detection by the JAX-RS run time

  • Interceptors can be chained and prioritized (using @Priority) and calling the proceed method of the WriterInterceptorContext automatically invokes the next interceptor in the chain or the MessageBodyWriter implementation itself
  • A WriterInterceptor acts as a wrapper around the MessageBodyWriter (invokes it internally)

Entity Providers (converting Java object to HTTP response payload)

  • The conversion of a Java object returned by the application code to HTTP response payload is done by a concrete class implementing the MessageBodyWriter interface
  • The writeTo method of the MessageBodyWriter implementation is where the action takes place. The JAX-RS run time passes in all the contextual information along with the OutputStream to which the which the response stream can be written to after conversion from its Java type

  • JAX-RS spec mandates that an implementation should contain out-of-of-the-box implementations of MessageBodyWriter interface for certain Java types like String, InputStream, File etc

Alright then ! This was a rather brief overview of how server side request processing works in JAX-RS and which components come into play.

Thanks for reading. Cheers !

References

Posted in Java, Java EE | Tagged , , , | Leave a comment