A. Service
What is a TAP resource? Which one are already existing? How to customize them or add other?
1. Resource management What is a TAP resource?
a. TAP endpoint = Web/TAP resource = 1 class
A TAP service can be seen as a collection of Web resources. Indeed, the IVOA specifies that a TAP service must have several "endpoints" identified by a name. By suffixing this name to the root URL of the TAP service, one can access easily to the corresponding endpoint. The IVOA lists the following standard endpoints:
- Availability
- Capabilities
- Tables
- Sync
- Async
All these endpoints are called "resources" in the TAP Library. By default, the library has one class for each of them. When the TAP service is being initialized, it creates one instance for each of the standard ones and stores them in an object of type "TAP". The links between these classes in the library can be represented like below:
You may have notice that except for the TAP endpoint Tables, all other standard endpoints are represented above with a class having the same name. By elimination, it can be deduced that the Tables endpoint is represented by the class TAPMetadata.
But, why a different name? Because this class is special: it has a double-purpose: representing a TAP resource AND fetching and managing all metadata about the published schemas, tables and columns. See B.2. TAP Metadata for more details.
b. Extensibility Possibility to add/replace/remove resources
As you see on the above UML class diagram, all the class representing a TAP resource/endpoint implement the same interface: TAPResource. Thus TAP can easily store and use them without knowning anything about their behavior. It just knows it is a resource and so it has a name - getName() - and can be, similarly as a Java Servlet, initialized - init(ServletConfig), executed - executeResource(HttpServletRequest, HttpServletResponse) - and destroyed - destroy().
Consequently, implementing this interface allows anybody to create its own TAP resource. Once done, using one of the following functions of the class TAP will let add this new resource to the service:
In order to execute the appropriate resource, TAP associate each given instance of TAPResource with its name in a map. By default, the name given by TAPResource.getName() is used, but it is possible to associate a resource with a different name ; hence the second addResource(...) function. However, for both of these functions, if the name of the new resource is already used by another listed resource, the former one will be replaced. Though the obvious risk that this behavior represents, it could be also really useful if you want to change the behavior of an existing (standard or not) resource.
RESOURCE_NAME containing the name the resource should have. For instance:
for Availability,
RESOURCE_NAME contains the string availability.
Their function getName() returns the value of this constant and can
not be overwritten.
Besides the addition/replacement of resources, it is also made possible to get the list of all TAP resources - getResources() - or to get a specific one - getResource(String name). This latter is particularly useful if you want to avoid replacing an existing resource.
And finally, resources can also be discarded thanks to removeResource(String name).
c. Provided ready-to-use resources HomePage & Examples
ForwardResource
ForwardResource is actually an abstract implementation of TAPResource. It does not implement any of the functions of its interface. It just add a convenient function either to make a redirection toward a given URL or to write the HTTP response using a specified local file: forward(String uri, String mimeType, HttpServletRequest, HttpServletResponse).
If no MIME type is provided, text/html will be used by default. However, the URI, the request and the response are required.
In function of the given URI, this function will perform a redirection or will write the content of a local file in the response.
| URI form | Example | Behavior |
|---|---|---|
/... | /home/me/myhomepage.html | File copy. Consider the URI as the absolute path of a local file. |
file://... | file:///home/me/myhomepage.html | |
... (containing no :) | html/myhomepage.html | File copy. Consider the URI as a path relative to the web application directory (i.e. directory containing WEB-INF |
http://... | URL redirection. Try to open a stream toward the given URI converted into a URL. | |
https://... | ||
ftp://... | ||
| anything else |
Home Page
As explained in Resources in TAPReminder, the IVOA does not specify any content for the root resource/endpoint of a TAP service ; in other words, no home page content is defined meaning that each TAP implementation is free to have its own and custom root endpoint.
Generally, this endpoint is an HTML document but it can be anything else. It can be a local server file, a redirection or a dynamic page (e.g. another Java Servlet, PHP document). Except for the dynamic page, all these cases can be easily implemented in a generic manner. It is the purpose of the TAP resource HomePage and the reason why this class extends ForwardResource.
As shown on the left, in order to use the forward function, a file path/URL and a document type are needed. Both may be provided by TAP if initialized (by a configuration file or manually):
If no home page URI is set, HomePage will return a default generated home page (of which
you can see a preview here). And as said opposite, if no MIME type is provided, the default
one - text/html - is used.
This resource is not a normal one. Because it aims to represent a resource at the root of a TAP service, it can not have a name (indeed, the URL of the home page is the same as the root URL of the TAP service).
In order to avoid confusion in the map of resources in TAP, the Home Page resource must not be stored inside this map. Instead, TAP has a special attribute just for this resource: homePage.
That's why if you want to change the home page file/URL, MIME type or completely its behavior, you must use one of the following functions:
Using TAP.addResource(...) will not have the desired effect: to be executed as the root resource of the TAP service.
Examples
This optional resource is not part of TAP 1.0, but has been introduced in TAP Implementation Notes 1.0 and IVOA Data Access Layer Interface 1.0. Even if the syntax they propose is slightly different, they have the same main ideas: providing a human-readable list of examples that can be parsed easily by a VO tool. Both use the same format: RDFa.
RDFa or Resource Description Framework in Attributes is a format extending HTML by allowing the addition of defined node attributes. These attributes are invisible and effectless for Web browsers (e.g. Firefox, Chrome, Safari, IE) and they give metadata which let a program/client find and extract specific information.
Read more about RDFaThe syntax described by these two IVOA documents is explained in more details and with an example in another page of this site: TAP Examples.
Consequently, the class Examples logically aims to provide a such HTML+RDFa document. However, generating it automatically would not allow an easy customization of its content and appearance. Thus, this class just performs a redirection to a specified file or URL, exactly as homePage does, except there is no default generated content in case of problem. So, in brief, the only line executed by Examples consists to call the function forward(String URI, String mime, ...).
No check on the syntax or on whether the XML attributes introduced by the TAP Implementation Notes or DALI are used and correctly set. As said, Examples just perform a redirection.
This also means that in case where the specified file/URL can not be found/reached, an error will be sent in response to the client.
Being an optional resource and a resource not defined in TAP 1.0, TAP does not create a such resource by default. You have to add one explicitly (either using the configuration file or by using the function TAP.addResource(...).