TJS JoinData Operation
The JoinData operation causes the server to merge the attribute data obtainable via a GetData request with its framework data. The server performs the join and prepares the output in the form requested by the client. The response includes the connection information required to access the output(s).
JoinData Request
Parameters
| Name | Presence | Description |
|---|---|---|
| Service | Required | Identifies service type. Must be "TJS". |
| Version | Required | Identifies service version. Defaults to the latest available version, currently 1.0 |
| Request | Required | Identifies service request. Must be "JoinData". |
| AcceptLanguages | Optional | Determines the language of the human-readable content of the response. Consists of a list of RFC 4646 language tags, comma-delimited and in order of preference. |
| FrameworkURI | Required | The URI of the spatial framework, as indicated in the DescribeFrameworks response. |
| GetDataURL | Required | URL which returns a valid TJS 1.0 GetData response. Note that this may be a TJS GetData request (via HTTP GET), a stored response to a GetData request, or a web process that returns content compliant with the GetData response schema. |
| StylingIdentifier | Optional | Name that identifies the type of styling to be invoked. Must be an Identifier listed in the DescribeJoinAbilities response. |
| StylingURL | Optional | URL that contains the styling information to be applied. This attribute shall contain a URL from which this input can be electronically retrieved. |
| Update | Optional | Boolean value ("true" or "false")that identifies if existing JoinData products should be updated by this service. If "true" then the service will attempt to update an existing set of JoinData products. If no such products exist it shall prepare JoinData products for this request in such a way that they can be updated by subsequent identical JoinData requests. (URLs for such products shall not vary for subsequent update requests.) Default is "false". |
Methods
HTTP GET method using KVP (mandatory)
All TJS servers shall implement HTTP GET transfer of the JoinData request, using KVP encoding. The KVP encoding of the JoinData request shall use the parameters specified above. An example of a JoinData request via HTTP GET is:
http://foo.bar/foo?
Service=TJS&
Version=1.0&
Request=GetData&
AcceptLanguages=en&
FrameworkURI=http://nrcan.gc.ca/Provinces/2001&
GetDataURL=http://foo.bar/foo&
StylingIdentifier=SLD&
StylingURL=http://foo.bar/foo&
Update=true
Note: URL encoding of KVP values in this example has been removed for clarity.
HTTP POST method using XML (optional)
TJS servers may also implement HTTP POST transfer of the JoinData operation request, using XML encoding only. The request parameters are encoded as XML elements, with their contents equivalent to those indicated in the parameter table shown above, and encoded according to the JoinData request XML schema. The following example indicates the contents and structure of a JoinData operation request encoded in XML.
<JoinData service="TJS" version="1.0" acceptLanguages="en" update="true">
<FrameworkURI>http://nrcan.gc.ca/Provinces/2001</FrameworkURI>
<GetDataURL>http://foo.bar/foo</GetDataURL>
<StylingIdentifier>SLD</StylingIdentifier>
<StylingURL>http://foo.bar/foo</StylingURL>
</JoinData>
JoinData Response
Schema
The normal response to a valid JoinData operation request shall be a JoinDataResponse data structure, which encodes attribute data along with associated metadata. JoinDataResponse is encoded in XML according to the JoinData response XML schema.
Examples
Exceptions
When a TJS server encounters an error while performing a JoinData operation, it shall return an exception report message as specified in Clause 8 of [OGC 06-121r3]. The allowed exception codes shall include those listed below.
| exceptionCode value | Meaning of code | "locator" value |
|---|---|---|
| MissingParameterValue | Operation request does not include a parameter value, and this server did not declare a default value for that parameter | Name of missing parameter |
| InvalidParameterValue | Operation request contains an invalid parameter value | Name of parameter with invalid value |
| NoApplicableCode | No other exceptionCode specified by this service and server applies to this exception | Omit "locator" parameter or specify the vendor specific exception code |
| NotEnoughStorage | The server does not have enough space available to store the inputs and outputs associated with the request. | None, omit "locator" parameter |
| InvalidFramework | The Framework identified in the GetData request did not match a Framework available for the JoinData operation on this server. | None, omit "locator" parameter |
| GetDataFailed | The Getdata request failed. | None, omit "locator" parameter |
| InvalidKey | The Join operation was unable to complete because the contents of the relate keys did not match correctly. | None, omit "locator" parameter |
Examples
For more information on structuring requests, please see the TJS Standard.