io.cdap.cdap.api.service.http

Interface HttpServiceHandler<T extends HttpServiceContext,V extends HttpServiceConfigurer>

Type Parameters:

T - type of service context

V - type of service configurer

All Superinterfaces:

ProgramLifecycle<T>

All Known Implementing Classes:

AbstractCubeHttpHandler, AbstractHttpServiceHandler

public interface HttpServiceHandler<T extends HttpServiceContext,V extends HttpServiceConfigurer>
extends ProgramLifecycle<T>

Interface to be implemented to handle HTTP requests. This interface can be implemented and passed along to custom user services. Classes that implement this interface can add methods with the @Path annotation to specify the endpoint which that method handles. It can also use the @GET, @POST, @PUT, @DELETE annotations to specify the type of HTTP requests that it handles.

Example:

      public class MyHttpHandler implements HttpServiceHandler {

         @GET
         @Path("/ping")
        public void process(HttpServiceRequest request, HttpServiceResponder responder) {
          responder.sendString("Hello World");
        }

         @Override
        public void configure(HttpServiceConfigurer configurer) { }

         @Override
        public void initialize(HttpServiceContext context) throws Exception { }

         @Override
        public void destroy() { }
      }
   

To handle HTTP request with large body, it is better to have the handler method to return a HttpContentConsumer to avoid running out of memory. Similarly, to return a response with a large body, it is preferable to return respond with HttpContentProducer. By default, all handler methods are executed within an implicit transaction, that is, you can access datasets and perform transactional data operations from the handler method. In some cases, for example, if the handler does not need to perform data operations, or if the time it takes to complete all operations may exceed the transaction timeout, it is better to annotate the method with a different transaction policy, for example:

@GET @Path("/ping") @TransactionPolicy(TransactionControl.EXPLICIT) public void process(HttpServiceRequest request, HttpServiceResponder responder) { getContext().execute(60, new TxRunnable() { // perform data operations }); responder.sendString("Hello World"); }

See Also:

HttpContentConsumer, HttpContentProducer

Method Summary

Modifier and Type	Method and Description
void	configure(V configurer) Configures this HttpServiceHandler with the given HttpServiceConfigurer.
void	destroy() Invoked whenever an instance of this HttpServiceHandler is destroyed.
void	initialize(T context) Invoked whenever a new instance of this HttpServiceHandler is created.

Method Detail

configure

void configure(V configurer)

Configures this HttpServiceHandler with the given HttpServiceConfigurer. This method is invoked at deployment time.

Parameters:

configurer - the HttpServiceConfigurer which is used to configure this Handler

initialize

void initialize(T context)
         throws Exception

Invoked whenever a new instance of this HttpServiceHandler is created. Note that this can happen at any time, because handler instances expire after a period of inactivity and are recreated when there is need for a new handler to serve an incoming request. That means that the time it takes to initialize adds to the time it takes to serve the request. It is therefore recommended to keep this method very lightweight.

Specified by:

initialize in interface ProgramLifecycle<T extends HttpServiceContext>

Parameters:

context - An instance of RuntimeContext

Throws:

Exception - If there is any error during initialization.

destroy

void destroy()

Invoked whenever an instance of this HttpServiceHandler is destroyed. This may happen when the service is shut down, or when a handler instance expires due to inactivity.

Specified by:

destroy in interface ProgramLifecycle<T extends HttpServiceContext>