public class TAP extends java.lang.Object implements VOSIResource
At its creation it is creating and configuring the other resources in function of the given description of the TAP service.
Modifier and Type | Field and Description |
---|---|
protected ServiceErrorWriter |
errorWriter
Object to use when an error occurs or comes until this resource from the others.
|
protected HomePage |
homePage
HOME PAGE resource.
|
protected java.lang.String |
homePageMimeType
MIME type of the custom home page.
|
protected java.lang.String |
homePageURI
URI of the page or path of the file to display when this resource is requested.
|
protected static java.lang.String |
lastRequestID
Last generated request ID.
|
static java.lang.String |
RESOURCE_ASYNC
Name of the TAP ASYNC resource.
|
static java.lang.String |
RESOURCE_AVAILABILITY
Name of the TAP AVAILABILITY resource.
|
static java.lang.String |
RESOURCE_CAPABILITIES
Name of the TAP CAPABILITIES resource.
|
static java.lang.String |
RESOURCE_METADATA
Name of the TAP TABLES resource.
|
static java.lang.String |
RESOURCE_SYNC
Name of the TAP SYNC resource.
|
protected java.util.Map<java.lang.String,TAPResource> |
resources
List of all the other TAP resources of the service.
|
protected ServiceConnection |
service
Description of the TAP service owning this resource.
|
protected java.lang.String |
tapBaseURL
Base URL of the TAP service.
|
static java.lang.String |
VERSION
Version of the TAP protocol used in this library.
|
Constructor and Description |
---|
TAP(ServiceConnection serviceConnection)
Build a HOME resource of a TAP service whose the description is given in
parameter.
|
Modifier and Type | Method and Description |
---|---|
boolean |
addResource(java.lang.String resourceId,
TAPResource newResource)
Add the given resource in this TAP service with the given ID (which will be also the URI to access this resource).
|
boolean |
addResource(TAPResource newResource)
Add the given resource in this TAP service.
|
protected void |
appendDataModels(java.lang.StringBuffer xml,
java.lang.String linePrefix)
List and declare all IVOA Data Models supported by this TAP service.
|
protected void |
appendObsCoreDM(java.lang.StringBuffer xml,
java.lang.String linePrefix)
Append the ObsCore DM declaration in the given
StringBuffer
if an ivoa.Obscore table can be found in TAP_SCHEMA . |
protected void |
appendRegTAPDM(java.lang.StringBuffer xml,
java.lang.String linePrefix)
Append the RegTAP DM declaration in the given
StringBuffer
if a schema rr can be found in TAP_SCHEMA
with all its required tables. |
void |
destroy()
Free all the resources used by this resource and the other managed resources.
|
void |
executeRequest(javax.servlet.http.HttpServletRequest request,
javax.servlet.http.HttpServletResponse response)
Execute the given request in the TAP service by forwarding it to the appropriate resource.
|
protected java.lang.String |
generateRequestID(javax.servlet.http.HttpServletRequest request)
Generate a unique ID for the given request.
|
java.lang.String |
getAccessURL()
Get the URL which lets access this resource.
|
ASync |
getASync()
Get the /async resource of this TAP service.
|
Availability |
getAvailability()
Get the /availability resource of this TAP service.
|
Capabilities |
getCapabilities()
Get the /capabilities resource of this TAP service.
|
java.lang.String |
getCapability()
Get the capabilities of this resource.
|
ServiceErrorWriter |
getErrorWriter()
Get the object to use in order to report errors to the user in replacement of the expected result.
|
HomePage |
getHomePage()
Get the HOME PAGE resource of this TAP service.
|
java.lang.String |
getHomePageMimeType()
Get the MIME type of the custom home page.
|
java.lang.String |
getHomePageURI()
Get the URL or the file path of a custom home page.
|
TAPLog |
getLogger()
Get the logger used by this resource and all the other resources managed by it.
|
int |
getNbResources()
Get the number of all resources managed by this TAP service (this resource - HOME - excluded).
|
TAPResource |
getResource(java.lang.String resourceId)
Get the specified resource.
|
java.util.Iterator<TAPResource> |
getResources()
Let iterate over the full list of the TAP resources managed by this TAP service.
|
ServiceConnection |
getServiceConnection()
Get the description of this service.
|
java.lang.String |
getStandardID()
Get the standardID of this endpoint of the VOSI interface.
|
Sync |
getSync()
Get the /sync resource of this TAP service.
|
TAPMetadata |
getTAPMetadata()
Get the object managing all the metadata (information about the published columns and tables)
of this TAP service.
|
java.util.Iterator<TAPResource> |
getTAPResources()
Deprecated.
The name of this function has been normalized. So now, you should use
getResources()
which is doing exactly the same thing. |
UWSService |
getUWS()
Get the UWS service used for the /async service.
|
boolean |
hasResource(java.lang.String resourceId)
Tell whether a resource is already associated with the given ID/URI.
|
void |
init(javax.servlet.ServletConfig config)
Let initialize this resource and all the other managed resources.
|
TAPResource |
removeResource(java.lang.String resourceId)
Remove the resource associated with the given ID/URI.
|
void |
setErrorWriter(ServiceErrorWriter errorWriter)
Set the object to use in order to report errors to the user in replacement of the expected result.
|
void |
setHomePage(HomePage newHomePageResource)
Change the whole behavior of the TAP home page.
|
void |
setHomePageMimeType(java.lang.String mime)
Set the MIME type of the custom home page.
|
void |
setHomePageURI(java.lang.String uri)
Set the URL or the file path of a custom home page.
|
void |
setTAPBaseURL(javax.servlet.http.HttpServletRequest request)
Build the base URL from the given HTTP request, and use it to set the base URL of this TAP service.
|
void |
setTAPBaseURL(java.lang.String baseURL)
Set the base URL of this TAP service.
|
public static final java.lang.String VERSION
public static final java.lang.String RESOURCE_AVAILABILITY
This resource tells whether the TAP service is available (i.e. whether it accepts queries or not).
Note: This name is suffixing the root TAP URL in order to access one of its resources.
public static final java.lang.String RESOURCE_CAPABILITIES
This resource list all capabilities (e.g. output limits and formats, uploads, ...) of this TAP resource.
Note: This name is suffixing the root TAP URL in order to access one of its resources.
public static final java.lang.String RESOURCE_METADATA
This resource lists and describes all published and query-able schemas, tables and columns.
Note: This name is suffixing the root TAP URL in order to access one of its resources.
public static final java.lang.String RESOURCE_ASYNC
This resource is used to submit ADQL queries to run asynchronously.
Note: This name is suffixing the root TAP URL in order to access one of its resources.
public static final java.lang.String RESOURCE_SYNC
This resource is used to submit ADQL queries to run synchronously.
Note: This name is suffixing the root TAP URL in order to access one of its resources.
protected final ServiceConnection service
protected final java.util.Map<java.lang.String,TAPResource> resources
protected java.lang.String tapBaseURL
protected HomePage homePage
HOME PAGE resource. This resource lets write the home page.
Note:
at the URI homePageURI
or it is a very simple HTML page listing the link of all available
TAP resources.
protected java.lang.String homePageURI
protected java.lang.String homePageMimeType
protected ServiceErrorWriter errorWriter
protected static java.lang.String lastRequestID
public TAP(ServiceConnection serviceConnection) throws UWSException, TAPException
ServiceConnection
.serviceConnection
- Description of the TAP service.UWSException
- If an error occurs while creating the /async
resource.TAPException
- If any other error occurs.public final TAPLog getLogger()
public void init(javax.servlet.ServletConfig config) throws javax.servlet.ServletException
Let initialize this resource and all the other managed resources.
This function is called by the library just once: when the servlet is initialized.
config
- Configuration of the servlet.javax.servlet.ServletException
- If any error occurs while reading the given configuration.TAPResource.init(ServletConfig)
public void destroy()
Free all the resources used by this resource and the other managed resources.
This function is called by the library just once: when the servlet is destroyed.
TAPResource.destroy()
public void setTAPBaseURL(java.lang.String baseURL)
Set the base URL of this TAP service.
This URL must be the same as the one of this resource ; it corresponds to the URL of the root (or home) of the TAP service.
The given URL will be propagated to the other TAP resources automatically.
baseURL
- URL of this resource.TAPResource.setTAPBaseURL(String)
public void setTAPBaseURL(javax.servlet.http.HttpServletRequest request)
Build the base URL from the given HTTP request, and use it to set the base URL of this TAP service.
The given URL will be propagated to the other TAP resources automatically.
request
- HTTP request from which a TAP service's base URL will be extracted.setTAPBaseURL(String)
public final ServiceConnection getServiceConnection()
public final Availability getAvailability()
public final Capabilities getCapabilities()
public final Sync getSync()
public final ASync getASync()
public final UWSService getUWS()
public final TAPMetadata getTAPMetadata()
Get the object managing all the metadata (information about the published columns and tables) of this TAP service.
This object is also to the /tables resource.
public final boolean addResource(TAPResource newResource)
Add the given resource in this TAP service.
The ID of this resource (which is also its URI) will be its name (given by TAPResource.getName()
).
WARNING:
If another resource with an ID strictly identical (case sensitively) to the name of the given resource, it will be overwritten!
You should check (thanks to hasResource(String)
) before calling this function that no resource is associated with the same URI.
If it is the case, you should then use the function addResource(String, TAPResource)
with a different ID/URI.
Note:
This function is equivalent to addResource(String, TAPResource)
with TAPResource.getName()
in first parameter.
newResource
- Resource to add in the service.addResource(String, TAPResource)
public final boolean addResource(java.lang.String resourceId, TAPResource newResource)
Add the given resource in this TAP service with the given ID (which will be also the URI to access this resource).
WARNING:
If another resource with an ID strictly identical (case sensitively) to the name of the given resource, it will be overwritten!
You should check (thanks to hasResource(String)
) before calling this function that no resource is associated with the same URI.
If it is the case, you should then use the function addResource(String, TAPResource)
with a different ID/URI.
Note: If the given ID is NULL, the name of the resource will be used.
resourceId
- ID/URI of the resource to add.newResource
- Resource to add.public final int getNbResources()
public final TAPResource getResource(java.lang.String resourceId)
Get the specified resource.
Note: The research is case sensitive.
resourceId
- Exact ID/URI of the resource to get.public final java.util.Iterator<TAPResource> getResources()
@Deprecated public final java.util.Iterator<TAPResource> getTAPResources()
getResources()
which is doing exactly the same thing.public final boolean hasResource(java.lang.String resourceId)
Tell whether a resource is already associated with the given ID/URI.
Note: The research is case sensitive.
resourceId
- Exact ID/URI of the resource to find.public final TAPResource removeResource(java.lang.String resourceId)
Remove the resource associated with the given ID/URI.
Note: The research is case sensitive.
resourceId
- Exact ID/URI of the resource to remove.public final ServiceErrorWriter getErrorWriter()
public final void setErrorWriter(ServiceErrorWriter errorWriter)
errorWriter
- Error writer to use. (if NULL, nothing will be done)public java.lang.String getStandardID()
VOSIResource
Get the standardID of this endpoint of the VOSI interface.
The standard IDs of the VOSI endpoints are the following:
getStandardID
in interface VOSIResource
public java.lang.String getAccessURL()
VOSIResource
getAccessURL
in interface VOSIResource
public java.lang.String getCapability()
VOSIResource
getCapability
in interface VOSIResource
protected void appendDataModels(java.lang.StringBuffer xml, java.lang.String linePrefix)
Currently, only the following DMs are natively supported:
More can be supported by extending this function (but not overwriting it completely otherwise the above supported DMs won't be anymore).
A DM declaration should follow this XML syntax:
<dataModel ivo-id="{DM-IVO_ID}">{DM-NAME}</dataModel>
xml
- The /capabilities
in-progress content in which
implemented DMs can be declared.linePrefix
- Tabulations/Spaces that should prefix all lines
(for human readability).protected void appendObsCoreDM(java.lang.StringBuffer xml, java.lang.String linePrefix)
Append the ObsCore DM declaration in the given StringBuffer
if an ivoa.Obscore
table can be found in TAP_SCHEMA
.
This function has no effect if ivoa.Obscore
can not
be found. The ivoa
schema is searched case sensitively,
but not the table name Obscore
which can be written
in any possible case.
If an ivoa.Obscore
table is found, this function
detects automatically which version of Obscore is implemented.
It will be declared as Obscore 1.1 if ALL the following columns
are found (case INsensitively): s_xel1
, x_xel2
,
t_xel
, em_xel
and pol_xel
.
If not, the Obscore table will be declared as Obscore 1.0.
xml
- The /capabilities
in-progress content
in which Obscore-DM should be declared if found.linePrefix
- Tabulations/Spaces that should prefix all lines
(for human readability).TAPMetadata.getObsCoreTable()
protected void appendRegTAPDM(java.lang.StringBuffer xml, java.lang.String linePrefix)
Append the RegTAP DM declaration in the given StringBuffer
if a schema rr
can be found in TAP_SCHEMA
with all its required tables.
This function has no effect if the schema rr
or its
mandatory children tables can not be found. The research is done
case sensitively by TAPMetadata.getRegTAPSchema()
.
If there is a valid schema rr
, this function
detects automatically which version of RegTAP is implemented. For the
moment only one is supported: RegTAP-1.0.
xml
- The /capabilities
in-progress content
in which RegTAP-DM should be declared if found.linePrefix
- Tabulations/Spaces that should prefix all lines
(for human readability).TAPMetadata.getRegTAPSchema()
public final HomePage getHomePage()
public final void setHomePage(HomePage newHomePageResource)
Change the whole behavior of the TAP home page.
Note:
If the given resource is NULL, the default home page (i.e. HomePage
) is set.
newHomePageResource
- The new HOME PAGE resource for this TAP service.public final java.lang.String getHomePageURI()
Get the URL or the file path of a custom home page.
The home page will be displayed when this resource is directly requested.
Note:
This function has a sense only if the HOME PAGE resource of this TAP service
is still the default home page (i.e. HomePage
).
public final void setHomePageURI(java.lang.String uri)
Set the URL or the file path of a custom home page.
The home page will be displayed when this resource is directly requested.
Note:
This function has a sense only if the HOME PAGE resource of this TAP service
is still the default home page (i.e. HomePage
).
uri
- URL or file path of the file to display as home page, or NULL to display the default home page.public final java.lang.String getHomePageMimeType()
Get the MIME type of the custom home page.
By default, it is the same as the default home page: "text/html".
Note:
This function has a sense only if the HOME PAGE resource of this TAP service
is still the default home page (i.e. HomePage
).
public final void setHomePageMimeType(java.lang.String mime)
Set the MIME type of the custom home page.
A NULL value will be considered as "text/html".
Note:
This function has a sense only if the HOME PAGE resource of this TAP service
is still the default home page (i.e. HomePage
).
mime
- MIME type of the custom home page.protected java.lang.String generateRequestID(javax.servlet.http.HttpServletRequest request)
Generate a unique ID for the given request.
By default, a timestamp is returned.
request
- Request whose an ID is asked.public void executeRequest(javax.servlet.http.HttpServletRequest request, javax.servlet.http.HttpServletResponse response) throws javax.servlet.ServletException, java.io.IOException
Execute the given request in the TAP service by forwarding it to the appropriate resource.
If the appropriate resource is the home page, the request is propagated to a TAPResource
(by default HomePage
) whose the resource name is "HOME PAGE". Once called, this resource
displays directly the home page in the given response by calling.
The default implementation of the default implementation (HomePage
) takes several cases into account.
Those are well documented in the Javadoc of HomePage
. What you should know, is that sometimes it is
using the following attributes of this class: getHomePage()
, getHomePageURI()
, getHomePageMimeType()
.
Only this resource (the root) should write any errors in the response. For that, it catches any Throwable
and
write an appropriate message in the HTTP response. The format and the content of this message is designed by the ServiceErrorWriter
set in this class. By changing it, it is then possible to change, for instance, the format of the error responses.
Each request is identified by a unique identifier (see generateRequestID(HttpServletRequest)
).
This ID is used only for logging purpose. Request and jobs/threads can then be associated more easily in the logs.
Besides, every requests and their response are logged as INFO with this ID.
request
- Request of the user to execute in this TAP service.response
- Object in which the result of the request must be written.javax.servlet.ServletException
- If any grave/fatal error occurs.java.io.IOException
- If any error occurs while reading or writing from or into a stream (and particularly the given request or response).