tap.resource

Interface TAPResource

All Known Implementing Classes:

ASync, Availability, Capabilities, Examples, ForwardResource, HomePage, Sync, TAPMetadata

public interface TAPResource

List the common functions that a TAP resource must have. Basically, any TAP resource may be initialized, may be destroyed, must have a name and must execute a request provided by its TAP service.

Important note: It is strongly recommended that the name of the TAP resource is also provided through a public static attribute named "RESOURCE_NAME". If this attribute exists, its value must be the same as the one returned by getName().

Version:

2.0 (09/2014)

Author:

Grégory Mantelet (CDS;ARI)

Method Summary

Modifier and Type	Method and Description
void	destroy() Let free properly all system/file/DB resources kept opened by this TAP resource.
boolean	executeResource(javax.servlet.http.HttpServletRequest request, javax.servlet.http.HttpServletResponse response) Interpret the given request, execute the appropriate action and finally return a result or display information to the user.
java.lang.String	getName() Get the name of this TAP resource.
void	init(javax.servlet.ServletConfig config) Let initialize this TAP resource.
void	setTAPBaseURL(java.lang.String baseURL) Let diffuse the base URL of the TAP service to all its TAP resources.

Method Detail

init

void init(javax.servlet.ServletConfig config)
   throws javax.servlet.ServletException

Let initialize this TAP resource.

Parameters:

config - Servlet configuration. (may be useful for the configuration of this resource)

Throws:

javax.servlet.ServletException - If any error prevent the initialization of this TAP resource. In case a such exception is thrown, the service should stop immediately.

destroy

void destroy()

Let free properly all system/file/DB resources kept opened by this TAP resource.

setTAPBaseURL

void setTAPBaseURL(java.lang.String baseURL)

Let diffuse the base URL of the TAP service to all its TAP resources.

Important note: This function should be called just once: either at the creation of the service or when the first request is sent to the TAP service (in this case, the request is also used to finish the initialization of the TAP service, and of all its resources).

Parameters:

baseURL - Common URL/URI used in all requests sent by any user to the TAP service.

getName

java.lang.String getName()

Get the name of this TAP resource.

Important note: This name MUST NOT be NULL and SHOULD NEVER change.

Returns:

Name of this TAP resource.

executeResource

boolean executeResource(javax.servlet.http.HttpServletRequest request,
                        javax.servlet.http.HttpServletResponse response)
                 throws java.io.IOException,
                        TAPException

Interpret the given request, execute the appropriate action and finally return a result or display information to the user.

IMPORTANT: "TAP resources can not take the law in their own hands!" :-) Errors that could occur inside this function should not be written directly in the given HttpServletResponse. They should be thrown to the resources executor: an instance of TAP, which will fill the HttpServletResponse with the error in the format described by the IVOA standard - VOTable. Besides, TAP may also add more information and may log the error (in function of this type).

Parameters:

request - Request sent by the user and which should be interpreted/executed here.

response - Response in which the result of the request must be written.

Returns:

true if the request has been successfully executed, false otherwise (but generally an exception will be sent if the request can't be executed).

Throws:

java.io.IOException - If any error occurs while writing the result of the given request.

TAPException - If any other error occurs while interpreting and executing the request or by formating and writing its result.