com.hivemq.spi.services.rest

Interface RESTService

@ThreadSafe
public interface RESTService

This HiveMQ REST service allows to expose Java Servlets (3.0), Filters and JAX-RS (2.0) resources.

The REST service has a listener concept so different resources can be bound to different transports (TCP / TLS) and different ports on different interfaces.

The REST Service supports first-class dependency injection and even allows to use constructor injection.

It's possible to annotate JAX-RS resources with Singleton to bind a resource to a singleton context instead of a per-request context.

The REST Service implementation is guaranteed to be thread safe.

Since:

3.0

Author:

Dominik Obermaier

Method Summary

Methods

Modifier and Type	Method and Description
void	addContextResolver(Class<? extends javax.ws.rs.ext.ContextResolver> contextResolver) Adds an ContextResolver to all available listeners.
void	addContextResolver(Class<? extends javax.ws.rs.ext.ContextResolver> contextResolver, Collection<String> listenerIdentifier) Adds an ContextResolver to all specified listeners.
void	addExceptionMapper(Class<? extends javax.ws.rs.ext.ExceptionMapper<? extends Throwable>> exceptionMapper) Adds an ExceptionMapper to all available listeners.
void	addExceptionMapper(Class<? extends javax.ws.rs.ext.ExceptionMapper<? extends Throwable>> exceptionMapper, Collection<String> listenerIdentifier) Adds an ExceptionMapper to all specified listeners.
void	addExceptionMapper(javax.ws.rs.ext.ExceptionMapper<? extends Throwable> exceptionMapper) Adds an ExceptionMapper to all available listeners.
void	addExceptionMapper(javax.ws.rs.ext.ExceptionMapper<? extends Throwable> exceptionMapper, Collection<String> listenerIdentifier) Adds an ExceptionMapper to all specified listeners.
<T extends javax.servlet.Filter> T	addFilter(ServletFilter<T> filter, String path) Adds a specific ServletFilter with a given path to the RESTService on all available listeners.
<T extends javax.servlet.Filter> T	addFilter(ServletFilter<T> filter, String path, Collection<String> listeners) Adds a specific ServletFilter with a given path to the RESTService on specific listeners.
void	addJaxRsApplication(javax.ws.rs.core.Application application) Adds a Application to the RESTService.
void	addJaxRsApplication(javax.ws.rs.core.Application application, Collection<String> listenerIdentifiers) Adds a Application to the RESTService.
void	addJaxRsResources(Class<?>... resources) Adds an arbitrary number of JAX-RS resources to all available listeners.
void	addJaxRsResources(Collection<Class<?>> resources, Collection<String> listenerIdentifiers) Adds an arbitrary number of JAX-RS resources to all specified listeners.
void	addJaxRsSingletons(Collection<Object> singletons, Collection<String> listenerIdentifiers) Adds all given JAX-RS resources as singleton to all specified listeners.
void	addJaxRsSingletons(Object... singletons) Adds all given JAX-RS resources as singleton to all available listeners.
void	addListener(Listener listener) Adds a new listener to the REST Service programmatically.
void	addMessageBodyReader(Class<? extends javax.ws.rs.ext.MessageBodyReader> messageBodyReader) Adds a MessageBodyReader to all listeners.
void	addMessageBodyReader(Class<? extends javax.ws.rs.ext.MessageBodyReader> messageBodyReader, Collection<String> listenerIdentifier) Adds a MessageBodyReader to all specified listeners.
void	addMessageBodyWriter(Class<? extends javax.ws.rs.ext.MessageBodyWriter> messageBodyWriter) Adds a MessageBodyWriter to all listeners.
void	addMessageBodyWriter(Class<? extends javax.ws.rs.ext.MessageBodyWriter> messageBodyWriter, Collection<String> listenerIdentifier) Adds a MessageBodyWriter to all specified listeners.
<T extends javax.servlet.http.HttpServlet> T	addServlet(Class<T> servlet, String path) Adds a servlet to a specific path and adds the servlet to all available listeners.
<T extends javax.servlet.http.HttpServlet> T	addServlet(Class<T> servlet, String path, Collection<String> listenerIdentifiers) Adds a servlet to a specific path and adds the servlet to all specified listeners.
void	addServlet(javax.servlet.http.HttpServlet servlet, String path) Adds a servlet instance to a specific path and adds the servlet to all available listeners.
void	addServlet(javax.servlet.http.HttpServlet servlet, String path, Collection<String> listenerIdentifiers) Adds a servlet instance to a specific path and adds the servlet to all specified listeners.
<T extends javax.servlet.http.HttpServlet> T	addServletWithFilters(Class<T> servlet, String path, Collection<String> listenerIdentifiers, ServletFilter<? extends javax.servlet.Filter>... filters) Adds a servlet to a specific path and adds the servlet to all specified listeners.
<T extends javax.servlet.http.HttpServlet> T	addServletWithFilters(Class<T> servlet, String path, ServletFilter<? extends javax.servlet.Filter>... filters) Adds a servlet to a specific path and adds the servlet to all available listeners.
void	addServletWithFilters(javax.servlet.http.HttpServlet servlet, String path, Collection<String> listenerIdentifiers, ServletFilter<? extends javax.servlet.Filter>... filters) Adds a servlet instance to a specific path and adds the servlet to all specific listeners.
void	addServletWithFilters(javax.servlet.http.HttpServlet servlet, String path, ServletFilter<? extends javax.servlet.Filter>... filters) Adds a servlet instance to a specific path and adds the servlet to all available listeners.
Collection<Listener>	getListeners() Returns an immutable view of all listeners.

Method Detail

addListener

void addListener(@NotNull
               Listener listener)

Adds a new listener to the REST Service programmatically.

Note: Typically the listeners are added via the configuration file. If adding the configuration via the config file does not suit your needs, the programmatic API offers a convenient way to add an arbitrary number of listeners at runtime.

Note: If you add listeners at runtime, existing servlets or JAX-RS resource on other listeners won't be added to this new listener automatically.

Parameters:

listener - the Listener implementation

Throws:

NullPointerException - if the passed listener is null

IllegalArgumentException - if the passed listener is not a valid listener type (like HttpListener

getListeners

@ReadOnly
Collection<Listener> getListeners()

Returns an immutable view of all listeners.

In order to get more information you need to downcast to a specific listener type. You can do this e.g. by code such as

 if (listener instanceof HttpListener) {
      HttpListener httpListener = (HttpListener) listener;
 }
 

Returns:

an immutable view of all listeners

addServlet

void addServlet(@NotNull
              javax.servlet.http.HttpServlet servlet,
              @NotNull
              String path)

Adds a servlet instance to a specific path and adds the servlet to all available listeners.

Parameters:

servlet - the servlet to add

path - the path to bind the servlet to

Throws:

NullPointerException - if the servlet or the path is null

addServlet

void addServlet(@NotNull
              javax.servlet.http.HttpServlet servlet,
              @NotNull
              String path,
              @NotNull
              Collection<String> listenerIdentifiers)

Adds a servlet instance to a specific path and adds the servlet to all specified listeners. If the collection of listeners is empty, the servlet will be added to all available listeners

Parameters:

servlet - the servlet to add

path - the path to bind the servlet to

listenerIdentifiers - a collection with identifiers of listeners

Throws:

NullPointerException - if the servlet, the path or the listener identifiers collection is null

addServlet

<T extends javax.servlet.http.HttpServlet> T addServlet(@NotNull
                                                      Class<T> servlet,
                                                      @NotNull
                                                      String path)

Adds a servlet to a specific path and adds the servlet to all available listeners.

The given servlet class will be instantiated by HiveMQ and the servlet can use dependency injection.

The servlet will be instantiated once and not per request, so it's essentially a singleton.

Dependency injection during a constructor is limited to com.hivemq.spi and JDK classes. You can use PostConstruct methods or addServlet(HttpServlet, String) instead.

Parameters:

servlet - the servlet to add

path - the path to bind the servlet to

Returns:

The instantiated servlet

Throws:

NullPointerException - if the servlet or the path is null

addServlet

<T extends javax.servlet.http.HttpServlet> T addServlet(@NotNull
                                                      Class<T> servlet,
                                                      @NotNull
                                                      String path,
                                                      @NotNull
                                                      Collection<String> listenerIdentifiers)

Adds a servlet to a specific path and adds the servlet to all specified listeners. If the collection of listeners is empty, the servlet will be added to all available listeners

The given servlet class will be instantiated by HiveMQ and the servlet can use dependency injection.

The servlet will be instantiated once and not per request, so it's essentially a singleton.

Dependency injection during a constructor is limited to com.hivemq.spi and JDK classes. You can use PostConstruct methods or addServlet(HttpServlet, String, Collection) instead.

Parameters:

servlet - the servlet to add

path - the path to bind the servlet to

listenerIdentifiers - a collection with identifiers of listeners

Returns:

The instantiated servlet

Throws:

NullPointerException - if the servlet or the path is null

addFilter

<T extends javax.servlet.Filter> T addFilter(@NotNull
                                           ServletFilter<T> filter,
                                           @NotNull
                                           String path)

Adds a specific ServletFilter with a given path to the RESTService on all available listeners.

Type Parameters:

T - the Filter which is contained in the ServletFilter

Parameters:

filter - the ServletFilter

path - the Path

Returns:

the concrete Filter instance

Throws:

NullPointerException - if the ServletFilter or path is null

addFilter

<T extends javax.servlet.Filter> T addFilter(@NotNull
                                           ServletFilter<T> filter,
                                           @NotNull
                                           String path,
                                           @NotNull
                                           Collection<String> listeners)

Adds a specific ServletFilter with a given path to the RESTService on specific listeners.

Type Parameters:

T - the Filter which is contained in the ServletFilter

Parameters:

filter - the ServletFilter

path - the Path

listeners - a collection of listeners

Returns:

the concrete Filter instance

Throws:

NullPointerException - if the ServletFilter, path or listener collection is null

addServletWithFilters

void addServletWithFilters(@NotNull
                         javax.servlet.http.HttpServlet servlet,
                         @NotNull
                         String path,
                         @NotNull
                         ServletFilter<? extends javax.servlet.Filter>... filters)

Adds a servlet instance to a specific path and adds the servlet to all available listeners.

Additionally a servlet filter is added directly to the servlet path mapping. This is a convenient method if you need a specific filter only for one servlet

Parameters:

servlet - the servlet to add

path - the path to bind the servlet to

filters - an arbitrary amount of filters for this specific servlet

Throws:

NullPointerException - if the servlet, the path or the filter array is null

addServletWithFilters

void addServletWithFilters(@NotNull
                         javax.servlet.http.HttpServlet servlet,
                         @NotNull
                         String path,
                         @NotNull
                         Collection<String> listenerIdentifiers,
                         @NotNull
                         ServletFilter<? extends javax.servlet.Filter>... filters)

Adds a servlet instance to a specific path and adds the servlet to all specific listeners.

Additionally a servlet filter is added directly to the servlet path mapping. This is a convenient method if you need a specific filter only for one servlet and only on specific listeners

Parameters:

servlet - the servlet to add

path - the path to bind the servlet to

listenerIdentifiers - a collection of listener identifierd

filters - an arbitrary amount of filters for this specific servlet

Throws:

NullPointerException - if the servlet, the path, the listener collection or the filter array is null

addServletWithFilters

<T extends javax.servlet.http.HttpServlet> T addServletWithFilters(@NotNull
                                                                 Class<T> servlet,
                                                                 @NotNull
                                                                 String path,
                                                                 @NotNull
                                                                 ServletFilter<? extends javax.servlet.Filter>... filters)

Adds a servlet to a specific path and adds the servlet to all available listeners. If the collection of listeners is empty, the servlet will be added to all available listeners

The given servlet class will be instantiated by HiveMQ and the servlet can use dependency injection.

Additionally a servlet filter is added directly to the servlet path mapping. This is a convenient method if you need a specific filter only for one servlet

Dependency injection during a constructor is limited to com.hivemq.spi and JDK classes. You can use PostConstruct methods or addServletWithFilters(HttpServlet, String, ServletFilter[]) instead.

Parameters:

servlet - the servlet to add

path - the path to bind the servlet to

filters - an arbitrary amount of filters for this specific servlet

Returns:

the instantiated servlet

Throws:

NullPointerException - if the servlet, the path or the filter array is null

addServletWithFilters

<T extends javax.servlet.http.HttpServlet> T addServletWithFilters(@NotNull
                                                                 Class<T> servlet,
                                                                 @NotNull
                                                                 String path,
                                                                 @NotNull
                                                                 Collection<String> listenerIdentifiers,
                                                                 @NotNull
                                                                 ServletFilter<? extends javax.servlet.Filter>... filters)

Adds a servlet to a specific path and adds the servlet to all specified listeners. If the collection of listeners is empty, the servlet will be added to all available listeners

The given servlet class will be instantiated by HiveMQ and the servlet can use dependency injection.

Additionally a servlet filter is added directly to the servlet path mapping. This is a convenient method if you need a specific filter only for one servlet

Dependency injection during a constructor is limited to com.hivemq.spi and JDK classes. You can use PostConstruct methods or addServletWithFilters(HttpServlet, String, Collection, ServletFilter[]) instead.

Parameters:

servlet - the servlet to add

path - the path to bind the servlet to

listenerIdentifiers - the collection of listeners

filters - an arbitrary amount of filters for this specific servlet

Returns:

the instantiated servlet

Throws:

NullPointerException - if the servlet, the path or the filter array is null

addJaxRsApplication

void addJaxRsApplication(@NotNull
                       javax.ws.rs.core.Application application)

Adds a Application to the RESTService.

Please be aware that when using this method, only all properties, classes and singletons are added to the RESTService, the Application and all annotations on the Application are ignored. So essentially this is a convenient method which allows you to add a lot of resources at once

Important: ApplicationPath annotations are ignored.

All resources defined in the Application will be added to all available listeners.

Parameters:

application - the Application

Throws:

NullPointerException - if the passed Application is null

addJaxRsApplication

void addJaxRsApplication(@NotNull
                       javax.ws.rs.core.Application application,
                       @NotNull
                       Collection<String> listenerIdentifiers)

Adds a Application to the RESTService.

Please be aware that when using this method, only all properties, classes and singletons are added to the RESTService, the Application and all annotations on the Application are ignored. So essentially this is a convenient method which allows you to add a lot of resources at once

Important: ApplicationPath annotations are ignored.

All resources defined in the Application will be added to all specified listeners.

Parameters:

application - the Application

listenerIdentifiers - a collection of listeners

Throws:

NullPointerException - if the passed Application or the collection of listeners is null

addJaxRsSingletons

void addJaxRsSingletons(@NotNull
                      Object... singletons)

Adds all given JAX-RS resources as singleton to all available listeners. Since you have to instantiate the singleton objects on your own, these singletons can't use dependency injection by HiveMQ and you have to pass your dependencies on your own to the objects.

If you want to have singletons which use dependency injection, consider using another method of the RESTService which accepts classes instead of objects. You can annotate these methods with Singleton

Parameters:

singletons - an arbitrary number of singleton resources

Throws:

NullPointerException - if the singleton array is null

addJaxRsSingletons

void addJaxRsSingletons(@NotNull
                      Collection<Object> singletons,
                      @NotNull
                      Collection<String> listenerIdentifiers)

Adds all given JAX-RS resources as singleton to all specified listeners. Since you have to instantiate the singleton objects on your own, these singletons can't use dependency injection by HiveMQ and you have to pass your dependencies on your own to the objects.

If you want to have singletons which use dependency injection, consider using another method of the RESTService which accepts classes instead of objects. You can annotate these methods with Singleton

Parameters:

singletons - an collection of singleton resources

listenerIdentifiers - a collection of listeners

Throws:

NullPointerException - if the singleton array is null

addJaxRsResources

void addJaxRsResources(@NotNull
                     Class<?>... resources)

Adds an arbitrary number of JAX-RS resources to all available listeners. These resources can use dependency injection and HiveMQ will instantiate the resources for you at runtime

Dependency injection during a constructor is limited to com.hivemq.spi and JDK classes. You can use PostConstruct methods or addJaxRsResources(Collection, Collection) instead.

Parameters:

resources - a arbitrary number of JAX-RS resource classes

Throws:

NullPointerException - if the resources array is null

addJaxRsResources

void addJaxRsResources(@NotNull
                     Collection<Class<?>> resources,
                     @NotNull
                     Collection<String> listenerIdentifiers)

Adds an arbitrary number of JAX-RS resources to all specified listeners. These resources can use dependency injection and HiveMQ will instantiate the resources for you at runtime

Dependency injection during a constructor or an PostConstruct method is limited.

Parameters:

resources - a collection of JAX-RS resource classes

listenerIdentifiers - a collection of listeners

Throws:

NullPointerException - if the resources array or the listener collection is null

addExceptionMapper

void addExceptionMapper(@NotNull
                      javax.ws.rs.ext.ExceptionMapper<? extends Throwable> exceptionMapper)

Adds an ExceptionMapper to all available listeners.

Since you have to instantiate the ExceptionMapper objects on your own, it can't use dependency injection by HiveMQ and you have to pass your dependencies on your own to the objects.

If you want to have ExceptionMappers which use dependency injection, consider using another method of the RESTService which accepts classes instead of objects.

Parameters:

exceptionMapper - the JAX-RS ExceptionMapper instance that should be added to all listeners

Throws:

NullPointerException - if the ExceptionMapper is null

Since:

3.2

addExceptionMapper

void addExceptionMapper(@NotNull
                      javax.ws.rs.ext.ExceptionMapper<? extends Throwable> exceptionMapper,
                      @NotNull
                      Collection<String> listenerIdentifier)

Adds an ExceptionMapper to all specified listeners.

Since you have to instantiate the ExceptionMapper objects on your own, it can't use dependency injection by HiveMQ and you have to pass your dependencies on your own to the objects.

If you want to have ExceptionMappers which use dependency injection, consider using another method of the RESTService which accepts classes instead of objects.

Parameters:

exceptionMapper - the JAX-RS ExceptionMapper instance that should be added to all specified listeners

listenerIdentifier - a collection of listeners

Throws:

NullPointerException - if the ExceptionMapper or the listener collection is null

Since:

3.2

addExceptionMapper

void addExceptionMapper(@NotNull
                      Class<? extends javax.ws.rs.ext.ExceptionMapper<? extends Throwable>> exceptionMapper)

Adds an ExceptionMapper to all available listeners.

The ExceptionMapper can use dependency injection and HiveMQ will instantiate it for you at runtime

Dependency injection during a constructor is limited to com.hivemq.spi and JDK classes. You can use PostConstruct methods or addExceptionMapper(ExceptionMapper) instead.

Parameters:

exceptionMapper - the JAX-RS ExceptionMapper class that should be added to all listeners

Throws:

NullPointerException - if the ExceptionMapper is null

Since:

3.2

addExceptionMapper

void addExceptionMapper(@NotNull
                      Class<? extends javax.ws.rs.ext.ExceptionMapper<? extends Throwable>> exceptionMapper,
                      @NotNull
                      Collection<String> listenerIdentifier)

Adds an ExceptionMapper to all specified listeners.

The ExceptionMapper can use dependency injection and HiveMQ will instantiate it for you at runtime

Dependency injection during a constructor is limited to com.hivemq.spi and JDK classes. You can use PostConstruct methods or addExceptionMapper(ExceptionMapper, Collection) instead.

Parameters:

exceptionMapper - the JAX-RS ExceptionMapper class that should be added to all specified listeners

listenerIdentifier - a collection of listeners

Throws:

NullPointerException - if the ExceptionMapper or the listener collection is null

Since:

3.2

addContextResolver

void addContextResolver(@NotNull
                      Class<? extends javax.ws.rs.ext.ContextResolver> contextResolver)

Adds an ContextResolver to all available listeners.

The ContextResolver can use dependency injection and HiveMQ will instantiate it for you at runtime

Dependency injection during a constructor is limited to com.hivemq.spi and JDK classes. You can use PostConstruct methods instead.

Parameters:

contextResolver - the JAX-RS ContextResolver class that should be added to all listeners

Throws:

NullPointerException - if the ContextResolver is null

Since:

3.2

addContextResolver

void addContextResolver(@NotNull
                      Class<? extends javax.ws.rs.ext.ContextResolver> contextResolver,
                      @NotNull
                      Collection<String> listenerIdentifier)

Adds an ContextResolver to all specified listeners.

The ContextResolver can use dependency injection and HiveMQ will instantiate it for you at runtime

Dependency injection during a constructor is limited to com.hivemq.spi and JDK classes. You can use PostConstruct methods instead.

Parameters:

contextResolver - the JAX-RS ContextResolver class that should be added to all specified listeners

listenerIdentifier - the collection of listeners

Throws:

NullPointerException - if the ContextResolver or the listener collection is null

Since:

3.2

addMessageBodyWriter

void addMessageBodyWriter(@NotNull
                        Class<? extends javax.ws.rs.ext.MessageBodyWriter> messageBodyWriter)

Adds a MessageBodyWriter to all listeners.

The MessageBodyWriter can use dependency injection and HiveMQ will instantiate it for you at runtime

Dependency injection during a constructor is limited to com.hivemq.spi and JDK classes. You can use PostConstruct methods instead.

Parameters:

messageBodyWriter - the JAX-RS MessageBodyWriter class that should be added to all listeners

Throws:

NullPointerException - if the MessageBodyWriter is null

Since:

3.2

addMessageBodyWriter

void addMessageBodyWriter(@NotNull
                        Class<? extends javax.ws.rs.ext.MessageBodyWriter> messageBodyWriter,
                        @NotNull
                        Collection<String> listenerIdentifier)

Adds a MessageBodyWriter to all specified listeners.

The MessageBodyWriter can use dependency injection and HiveMQ will instantiate it for you at runtime

Dependency injection during a constructor is limited to com.hivemq.spi and JDK classes. You can use PostConstruct methods instead.

Parameters:

messageBodyWriter - the JAX-RS MessageBodyWriter class that should be added to all specified listeners

listenerIdentifier - the collection of listeners

Throws:

NullPointerException - if the MessageBodyWriter or the listener collection is null

Since:

3.2

addMessageBodyReader

void addMessageBodyReader(@NotNull
                        Class<? extends javax.ws.rs.ext.MessageBodyReader> messageBodyReader)

Adds a MessageBodyReader to all listeners.

The MessageBodyReader can use dependency injection and HiveMQ will instantiate it for you at runtime

Dependency injection during a constructor is limited to com.hivemq.spi and JDK classes. You can use PostConstruct methods instead.

Parameters:

messageBodyReader - the JAX-RS MessageBodyReader class that should be added to all listeners

Throws:

NullPointerException - if the MessageBodyReader is null

Since:

3.2

addMessageBodyReader

void addMessageBodyReader(@NotNull
                        Class<? extends javax.ws.rs.ext.MessageBodyReader> messageBodyReader,
                        @NotNull
                        Collection<String> listenerIdentifier)

Adds a MessageBodyReader to all specified listeners.

The MessageBodyReader can use dependency injection and HiveMQ will instantiate it for you at runtime

Dependency injection during a constructor is limited to com.hivemq.spi and JDK classes. You can use PostConstruct methods instead.

Parameters:

messageBodyReader - the JAX-RS MessageBodyReader class that should be added to all specified listeners

listenerIdentifier - the collection of listeners

Throws:

NullPointerException - if the MessageBodyReader or the listener collection is null

Since:

3.2