com.hivemq.spi.services.rest.RESTService Maven / Gradle / Ivy
Go to download
Show more of this group Show more artifacts with this name
Show all versions of hivemq-spi Show documentation
Show all versions of hivemq-spi Show documentation
The Service Provider Interfaces for developing HiveMQ plugins.
package com.hivemq.spi.services.rest;
import com.hivemq.spi.annotations.NotNull;
import com.hivemq.spi.annotations.ReadOnly;
import com.hivemq.spi.annotations.ThreadSafe;
import com.hivemq.spi.services.rest.listener.HttpListener;
import com.hivemq.spi.services.rest.listener.Listener;
import com.hivemq.spi.services.rest.servlet.ServletFilter;
import javax.servlet.Filter;
import javax.servlet.http.HttpServlet;
import javax.ws.rs.core.Application;
import java.util.Collection;
/**
* 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 {@link @javax.inject.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.
*
* @author Dominik Obermaier
* @since 3.0
*/
@ThreadSafe
public interface RESTService {
/**
* 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.
*
* @param listener the {@link Listener} implementation
* @throws NullPointerException if the passed listener is null
* @throws IllegalArgumentException if the passed listener is not a valid listener type (like {@link HttpListener}
*/
void addListener(@NotNull Listener listener);
/**
* 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;
* }
*
*
* @return an immutable view of all listeners
*/
@ReadOnly
Collection getListeners();
/**
* Adds a servlet instance to a specific path and adds the servlet to all available listeners.
*
* @param servlet the servlet to add
* @param path the path to bind the servlet to
* @throws NullPointerException if the servlet or the path is null
*/
void addServlet(@NotNull HttpServlet servlet, @NotNull String path);
/**
* 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
*
* @param servlet the servlet to add
* @param path the path to bind the servlet to
* @param listenerIdentifiers a collection with identifiers of listeners
* @throws NullPointerException if the servlet, the path or the listener identifiers collection is null
*/
void addServlet(@NotNull HttpServlet servlet, @NotNull String path, @NotNull Collection listenerIdentifiers);
/**
* 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.
*
* @param servlet the servlet to add
* @param path the path to bind the servlet to
* @return The instantiated servlet
* @throws NullPointerException if the servlet or the path is null
*/
T addServlet(@NotNull Class servlet, @NotNull String path);
/**
* 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.
*
* @param servlet the servlet to add
* @param path the path to bind the servlet to
* @param listenerIdentifiers a collection with identifiers of listeners
* @return The instantiated servlet
* @throws NullPointerException if the servlet or the path is null
*/
T addServlet(@NotNull Class servlet, @NotNull String path, @NotNull Collection listenerIdentifiers);
/**
* Adds a specific {@link ServletFilter} with a given path to the RESTService on all available listeners.
*
* @param filter the {@link ServletFilter}
* @param path the Path
* @param the {@link Filter} which is contained in the {@link ServletFilter}
* @return the concrete {@link Filter} instance
* @throws NullPointerException if the {@link ServletFilter} or path is null
*/
T addFilter(@NotNull ServletFilter filter, @NotNull String path);
/**
* Adds a specific {@link ServletFilter} with a given path to the RESTService on specific listeners.
*
* @param filter the {@link ServletFilter}
* @param path the Path
* @param listeners a collection of listeners
* @param the {@link Filter} which is contained in the {@link ServletFilter}
* @return the concrete {@link Filter} instance
* @throws NullPointerException if the {@link ServletFilter}, path or listener collection is null
*/
T addFilter(@NotNull ServletFilter filter, @NotNull String path, @NotNull Collection listeners);
/**
* 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
*
* @param servlet the servlet to add
* @param path the path to bind the servlet to
* @param filters an arbitrary amount of filters for this specific servlet
* @throws NullPointerException if the servlet, the path or the filter array is null
*/
@SuppressWarnings("unchecked")
void addServletWithFilters(@NotNull HttpServlet servlet, @NotNull String path, @NotNull ServletFilter... 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
*
* @param servlet the servlet to add
* @param path the path to bind the servlet to
* @param listenerIdentifiers a collection of listener identifierd
* @param 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
*/
@SuppressWarnings("unchecked")
void addServletWithFilters(@NotNull HttpServlet servlet, @NotNull String path, @NotNull Collection listenerIdentifiers, @NotNull ServletFilter... 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
*
* @param servlet the servlet to add
* @param path the path to bind the servlet to
* @param filters an arbitrary amount of filters for this specific servlet
* @return the instantiated servlet
* @throws NullPointerException if the servlet, the path or the filter array is null
*/
@SuppressWarnings("unchecked")
T addServletWithFilters(@NotNull Class servlet, @NotNull String path, @NotNull ServletFilter... 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
*
* @param servlet the servlet to add
* @param path the path to bind the servlet to
* @param listenerIdentifiers the collection of listeners
* @param filters an arbitrary amount of filters for this specific servlet
* @return the instantiated servlet
* @throws NullPointerException if the servlet, the path or the filter array is null
*/
@SuppressWarnings("unchecked")
T addServletWithFilters(@NotNull Class servlet, @NotNull String path, @NotNull Collection listenerIdentifiers, @NotNull ServletFilter... filters);
/**
* Adds a {@link Application} to the RESTService.
*
* Please be aware that when using this method, only all properties, classes and singletons are
* added to the RESTService, the {@link Application} and all annotations on the {@link} Application
* are ignored. So essentially this is a convenient method which allows you to add a lot of resources at once
*
* Important: {@link javax.ws.rs.ApplicationPath} annotations are ignored.
*
* All resources defined in the Application will be added to all available listeners.
*
* @param application the {@link Application}
* @throws NullPointerException if the passed {@link Application} is null
*/
void addJaxRsApplication(@NotNull Application application);
/**
* Adds a {@link Application} to the RESTService.
*
* Please be aware that when using this method, only all properties, classes and singletons are
* added to the RESTService, the {@link Application} and all annotations on the {@link} Application
* are ignored. So essentially this is a convenient method which allows you to add a lot of resources at once
*
* Important: {@link javax.ws.rs.ApplicationPath} annotations are ignored.
*
* All resources defined in the Application will be added to all specified listeners.
*
* @param application the {@link Application}
* @param listenerIdentifiers a collection of listeners
* @throws NullPointerException if the passed {@link Application} or the collection of listeners is null
*/
void addJaxRsApplication(@NotNull Application application, @NotNull Collection listenerIdentifiers);
/**
* 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 {@link javax.inject.Singleton}
*
* @param singletons an arbitrary number of singleton resources
* @throws NullPointerException if the singleton array is null
*/
void addJaxRsSingletons(@NotNull Object... singletons);
/**
* 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 {@link javax.inject.Singleton}
*
* @param singletons an collection of singleton resources
* @param listenerIdentifiers a collection of listeners
* @throws NullPointerException if the singleton array is null
*/
void addJaxRsSingletons(@NotNull Collection