com.xatkit.core.server

Class XatkitServer

java.lang.Object

com.xatkit.core.server.XatkitServer

public class XatkitServer
extends Object

The REST server used to receive external webhooks.

The XatkitServer provides a simple REST API that accepts POST methods on port 5000. Incoming requests are parsed and sent to the registered WebhookEventProviders, that transform the original request into EventInstances that can be used to trigger actions.

See Also:

registerWebhookEventProvider(WebhookEventProvider)

Constructor Summary

Constructors

Constructor and Description
XatkitServer(Configuration configuration) Constructs a new XatkitServer with the given Configuration.

Method Summary

Modifier and Type	Method and Description
void	clearRegisteredRestHandlers() Clears the registered RestHandlers.
File	createOrReplacePublicFile(XatkitSession session, String path, byte[] content)
File	createOrReplacePublicFile(XatkitSession session, String path, File origin) Creates a publicly accessible file from the provided session, path, and origin.
File	createOrReplacePublicFile(XatkitSession session, String path, String content) Creates a publicly accessible file from the provided session, path, and content.
String	getBaseURL() Returns the URL of the XatkitServer.
protected org.apache.http.impl.bootstrap.HttpServer	getHttpServer() Returns the underlying HttpServer used to receive requests.
int	getPort() Returns the port the server is listening to.
File	getPublicFile(String filePath) Retrieves the public File associated to the provided filePath.
File	getPublicFile(XatkitSession session, String filePath) Retrieves the public File associated to the provided session and filePath.
String	getPublicURL(File file) Retrieves the public URL associated to the provided file if it exists.
RestHandler	getRegisteredRestHandler(HttpMethod httpMethod, String uri) Returns the RestHandler associated to the provided uri with the given httpMethod.
Collection<RestHandler>	getRegisteredRestHandlers() Returns a Collection containing the registered RestHandlers.
boolean	isRestEndpoint(HttpMethod httpMethod, String uri) Returns whether the provided httpMethod on the given uri is associated to a REST endpoint.
boolean	isStarted() Returns true if the XatkitServer is started, false otherwise.
Object	notifyRestHandler(HttpMethod httpMethod, String uri, List<org.apache.http.Header> headers, List<org.apache.http.NameValuePair> params, Object content, String contentType) Notifies the REST endpoint associated with the provided uri.
void	registerRestEndpoint(HttpMethod httpMethod, String uri, RestHandler handler) Registers the provided handler as a REST endpoint for the provided uri.
void	registerWebhookEventProvider(WebhookEventProvider webhookEventProvider) Register a WebhookEventProvider.
void	start() Starts the underlying HttpServer.
void	stop() Stops the underlying HttpServer.
void	unregisterWebhookEventProvider(WebhookEventProvider webhookEventProvider) Unregistered a WebhookEventProvider.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

XatkitServer

public XatkitServer(Configuration configuration)

Constructs a new XatkitServer with the given Configuration.

The provided Configuration is used to specify the port the server should listen to (see XatkitServerUtils.SERVER_PORT_KEY). If the Configuration does not specify a port the default value (5000) is used.

Note: this method does not start the underlying HttpServer. Use start() to start the HttpServer in a dedicated thread.

Parameters:

configuration - the Configuration used to initialize the XatkitServer

Throws:

NullPointerException - if the provided configuration is null

See Also:

start(), stop()

Method Detail

getPort

public int getPort()

Returns the port the server is listening to.

Returns:

the port the server is listening to

getBaseURL

public String getBaseURL()

Returns the URL of the XatkitServer.

This URL contains the base address and port (<address:port>), and can be used to access the XatkitServer handlers.

Returns:

the URL of the XatkitServer

getHttpServer

protected org.apache.http.impl.bootstrap.HttpServer getHttpServer()

Returns the underlying HttpServer used to receive requests.

Note: this method is protected for testing purposes, and should not be called by client code.

Returns:

the HttpServer used to receive requests

isStarted

public boolean isStarted()

Returns true if the XatkitServer is started, false otherwise.

Returns:

true if the XatkitServer is started, false otherwise

start

public void start()

Starts the underlying HttpServer.

This method registered a shutdown hook that is used to close the HttpServer when the application terminates. To manually close the underlying HttpServer see stop().

stop

public void stop()

Stops the underlying HttpServer.

registerRestEndpoint

public void registerRestEndpoint(HttpMethod httpMethod,
                                 String uri,
                                 RestHandler handler)

Registers the provided handler as a REST endpoint for the provided uri.

The provided handler will receive the HTTP requests that are sent to the provided uri through the notifyRestHandler(HttpMethod, String, List, List, Object, String) method.

Note: the provided uri must start with a leading /.

Parameters:

httpMethod - the Http method of the REST endpoint

uri - the URI of the REST endpoint

handler - the JsonRestHandler to associate to the REST endpoint

Throws:

NullPointerException - if the provided uri or handler is null

IllegalArgumentException - if the provided uri does not start with a leading /

isRestEndpoint

public boolean isRestEndpoint(HttpMethod httpMethod,
                              String uri)

Returns whether the provided httpMethod on the given uri is associated to a REST endpoint.

Parameters:

httpMethod - the Http method of the REST endpoint to check

uri - the URI of the REST endpoint to check

Returns:

true if there is a REST endpoint associated to the provided uri, false otherwise

Throws:

NullPointerException - if the provided uri is null

getRegisteredRestHandler

@Nullable
public RestHandler getRegisteredRestHandler(HttpMethod httpMethod,
                                                      String uri)

Returns the RestHandler associated to the provided uri with the given httpMethod.

Parameters:

httpMethod - the Http method to retrieve the handler for

uri - the URI to retrieve the handler for

Returns:

the retrieved RestHandler if it exists, null otherwise

getRegisteredRestHandlers

public Collection<RestHandler> getRegisteredRestHandlers()

Returns a Collection containing the registered RestHandlers.

Returns:

a Collection containing the registered RestHandlers

clearRegisteredRestHandlers

public void clearRegisteredRestHandlers()

Clears the registered RestHandlers.

This method only removes the uri -> handler bindings, and does not ensure the the RestHandlers have been properly stopped.

notifyRestHandler

public Object notifyRestHandler(HttpMethod httpMethod,
                                String uri,
                                List<org.apache.http.Header> headers,
                                List<org.apache.http.NameValuePair> params,
                                @Nullable
                                Object content,
                                String contentType)
                         throws RestHandlerException

Notifies the REST endpoint associated with the provided uri.

Parameters:

httpMethod - the Http method of the REST endpoint to notify

uri - the URI of the REST endpoint to notify

headers - the HTTP Headers of the request sent to the endpoint

params - the HTTP parameters of the request sent to the endpoint

content - the JsonElement representing the content of the request sent to the endpoint

Returns:

the JsonElement returned by the endpoint, or null if the endpoint does not return anything

Throws:

NullPointerException - if the provided uri, header, or params is null

XatkitException - if there is no REST endpoint registered for the provided uri

RestHandlerException - if an error occurred when processing the RestHandler's logic

See Also:

registerRestEndpoint(HttpMethod, String, RestHandler)

registerWebhookEventProvider

public void registerWebhookEventProvider(WebhookEventProvider webhookEventProvider)

Register a WebhookEventProvider.

The registered webhookEventProvider's handler will be notified when a new request is received. If the provider's handler supports the request content type (see RestHandler.acceptContentType(String), it will receive the request content that will be used to create the associated EventInstance.

Parameters:

webhookEventProvider - the WebhookEventProvider to register

Throws:

NullPointerException - if the provided webhookEventProvider is null

See Also:

(HttpMethod, String, List, List, Object, String), RestHandler.acceptContentType(String), RestHandler.handleContent(List, List, Object)

unregisterWebhookEventProvider

public void unregisterWebhookEventProvider(WebhookEventProvider webhookEventProvider)

Unregistered a WebhookEventProvider.

The provided webhookEventProvider will not be notified when new request are received, and cannot be used to create EventInstances.

Parameters:

webhookEventProvider - the WebhookEventProvider to unregister

Throws:

NullPointerException - if the provided webhookEventProvider is null

createOrReplacePublicFile

public File createOrReplacePublicFile(XatkitSession session,
                                      String path,
                                      File origin)

Creates a publicly accessible file from the provided session, path, and origin.

The created file can be accessed through <baseURL/content/sessionId/path>, and contains the content of the provided origin File.

Parameters:

session - the XatkitSession used to create the file

path - the path of the file to create

origin - the origin file to copy

Returns:

the created File

Throws:

NullPointerException - if the provided session, path, or origin is null

XatkitException - if an error occurred when reading the provided origin File, or if the existing file at the given path cannot be deleted or if the provided path refers to an illegal location

See Also:

createOrReplacePublicFile(XatkitSession, String, String)

createOrReplacePublicFile

public File createOrReplacePublicFile(XatkitSession session,
                                      String path,
                                      String content)

Creates a publicly accessible file from the provided session, path, and content.

The created file can be accessed through <baseURL/content/sessionId/path, and contains the provided content.

Parameters:

session - the XatkitSession used to create the file

path - the the path of the file to create

content - the content of the file to create

Returns:

the created File

Throws:

NullPointerException - if the provided session or path is null

XatkitException - if an error occurred when computing the provided path, or if the existing file at the given path cannot be deleted, or if the provided path refers to an illegal location

createOrReplacePublicFile

public File createOrReplacePublicFile(XatkitSession session,
                                      String path,
                                      byte[] content)

getPublicURL

@Nullable
public String getPublicURL(File file)

Retrieves the public URL associated to the provided file if it exists.

This method is typically called to retrieve the public URL of a file created with createOrReplacePublicFile(XatkitSession, String, String).

Parameters:

file - the File to retrieve the public URL for

Returns:

the retrieved URL if it exists, null otherwise

Throws:

NullPointerException - if the provided file is null

XatkitException - if the provided file corresponds to an illegal location

getPublicFile

@Nullable
public File getPublicFile(XatkitSession session,
                                    String filePath)

Retrieves the public File associated to the provided session and filePath.

Parameters:

session - the XatkitSession to retrieve the File from

filePath - the path of the File to retrieve

Returns:

the retrieved File if it exists, null otherwise

Throws:

NullPointerException - if the provided session if filePath is null

XatkitException - if the provided filePath refers to an illegal location

See Also:

getPublicFile(String)

getPublicFile

@Nullable
public File getPublicFile(String filePath)

Retrieves the public File associated to the provided filePath.

This method expects a full relative path under the /content/ location. This means that File associated to XatkitSessions must be retrieved with the following path: sessionId/path. Check getPublicFile(XatkitSession, String) to easily retrieve a File associated to a XatkitSession.

Parameters:

filePath - the path of the File to retrieve

Returns:

the retrieved File if it exists, null otherwise

Throws:

NullPointerException - if the provided filePath is null

XatkitException - if the provided filePath refers to an illegal location

See Also:

getPublicFile(XatkitSession, String)