org.myskua.sac.client
Interface SacClient

All Known Implementing Classes:

QsacSacClientImpl

public interface SacClient

Public interface for the (Meta-)SAC client. This interface hides the implementation details required to interact with a (Meta-)SAC and its services.

Author:

Kona Andrews, SKUA Project, kea@roe.ac.uk

Field Summary

static java.lang.String	CSV_CONTENT Mime-type for SPARQL query results as Comma-Separated Values
static java.lang.String	RDF_TEXT_CONTENT Mime-type for RDF N3
static java.lang.String	RDF_XML_CONTENT Mime-type for RDF XML
static java.lang.String	SPARQL_CONTENT Mime-type for SPARQL queries
static java.lang.String	SPARQL_RESULTS_CONTENT Mime-type for SPARQL query results as XML
static java.lang.String	TALIS_CHANGESET_CONTENT Mime-type for SPARQL query results as plaintext
static java.lang.String	TEXT_CONTENT Mime-type for SPARQL query results as plaintext
static java.lang.String	TSV_CONTENT Mime-type for SPARQL query results as Tab-Separated Values
static java.lang.String	TURTLE_CONTENT Mime-type for Turtle

Method Summary

java.lang.String	addClaim(java.lang.String sacEndpoint, java.lang.String claimXmlString, java.lang.String mimeType) SAC method to add a new claim to a SAC.
void	addDelegationTo(java.lang.String sacEndpoint, java.lang.String toSacEndpoint) SAC administration method to enable query forwarding (delegation) to a given SAC.
void	allowDelegationFrom(java.lang.String sacEndpoint, java.lang.String fromSacEndpoint) SAC administration method to enable query forwarding (delegation) to be accepted from a given SAC.
java.lang.String	createSac(java.lang.String metaSacEndpoint, java.lang.String sacName, java.lang.String sacMetadataXml) MetaSAC method to create a new SAC at the specified MetaSAC.
java.lang.String	createSac(java.lang.String metaSacEndpoint, java.lang.String sacName, java.lang.String sacMetadata, java.lang.String mimeType) MetaSAC method to create a new SAC at the specified MetaSAC.
void	deleteClaim(java.lang.String claimID) SAC method to delete the claim at the specified URL.
void	deleteSac(java.lang.String sacEndpoint) MetaSAC method to delete the SAC specified by the supplied SAC endpoint URL.
void	denyDelegationFrom(java.lang.String sacEndpoint, java.lang.String fromSacEndpoint) SAC administration method to prevent query forwarding (delegation) from being accepted from a given SAC.
void	dropDelegationTo(java.lang.String sacEndpoint, java.lang.String toSacEndpoint) SAC administration method to disable query forwarding (delegation) to a given SAC.
java.lang.String	getClaim(java.lang.String claimID) SAC method to retrieve the claim at the specified URL.
java.lang.String	getClaim(java.lang.String claimID, java.lang.String mimeType) SAC method to retrieve the claim at the specified URL.
Resource	getClaimAsResource(java.lang.String claimID) SAC method to retrieve the claim at the specified URL.
java.lang.String	getMetaSacInfo(java.lang.String metaSacEndpoint) MetaSAC method to return some HTML-formatted data about the MetaSAC.
java.lang.String	getSacContent(java.lang.String sacEndpoint) SAC method to retrieve the content of a SAC.
java.lang.String	getSacContent(java.lang.String sacEndpoint, java.lang.String mimeType) SAC method to retrieve the content of a SAC.
Resource	getSacContentAsResource(java.lang.String sacEndpoint) SAC method to retrieve the content of a SAC.
java.lang.String	getSacMetadata(java.lang.String sacEndpoint) SAC method to retrieve any metadata associated with the SAC.
java.lang.String	getSacMetadata(java.lang.String sacEndpoint, java.lang.String mimeType) SAC method to retrieve any metadata associated with the SAC.
Resource	getSacMetadataAsResource(java.lang.String sacEndpoint) SAC method to retrieve any metadata associated with the SAC.
void	replaceClaim(java.lang.String claimID, java.lang.String claimXmlString, java.lang.String mimeType) SAC method to replace a pre-existing claim.
java.lang.String	runQuery(java.lang.String sacEndpoint, java.lang.String sparql, java.lang.String mimeType) SAC method to run a SPARQL query against the SAC at the specified URL, and return the results of this query in the specified format.

Field Detail

RDF_XML_CONTENT

static final java.lang.String RDF_XML_CONTENT

Mime-type for RDF XML

See Also:

Constant Field Values

RDF_TEXT_CONTENT

static final java.lang.String RDF_TEXT_CONTENT

Mime-type for RDF N3

See Also:

Constant Field Values

TURTLE_CONTENT

static final java.lang.String TURTLE_CONTENT

Mime-type for Turtle

See Also:

Constant Field Values

SPARQL_CONTENT

static final java.lang.String SPARQL_CONTENT

Mime-type for SPARQL queries

See Also:

Constant Field Values

TEXT_CONTENT

static final java.lang.String TEXT_CONTENT

Mime-type for SPARQL query results as plaintext

See Also:

Constant Field Values

SPARQL_RESULTS_CONTENT

static final java.lang.String SPARQL_RESULTS_CONTENT

Mime-type for SPARQL query results as XML

See Also:

Constant Field Values

CSV_CONTENT

static final java.lang.String CSV_CONTENT

Mime-type for SPARQL query results as Comma-Separated Values

See Also:

Constant Field Values

TSV_CONTENT

static final java.lang.String TSV_CONTENT

Mime-type for SPARQL query results as Tab-Separated Values

See Also:

Constant Field Values

TALIS_CHANGESET_CONTENT

static final java.lang.String TALIS_CHANGESET_CONTENT

Mime-type for SPARQL query results as plaintext

See Also:

Constant Field Values

Method Detail

getMetaSacInfo

java.lang.String getMetaSacInfo(java.lang.String metaSacEndpoint)
                                throws SacClientException

MetaSAC method to return some HTML-formatted data about the MetaSAC. This might include a list of the available SACs, but its content is not formally specified.

Parameters:

metaSacEndpoint - The URL of the endpoint of the MetaSAC whose information is to be extracted.

Returns:

A String containing HTML-formatted data about the MetaSAC.

Throws:

SacClientException - if anything goes wrong, with an explanation of the problem in the exception message.

deleteSac

void deleteSac(java.lang.String sacEndpoint)
               throws SacClientException

MetaSAC method to delete the SAC specified by the supplied SAC endpoint URL.

Parameters:

sacEndpoint - The URL of the endpoint of the SAC to be deleted.

Throws:

SacClientException - if anything goes wrong, with an explanation of the problem in the exception message.

createSac

java.lang.String createSac(java.lang.String metaSacEndpoint,
                           java.lang.String sacName,
                           java.lang.String sacMetadataXml)
                           throws SacClientException

MetaSAC method to create a new SAC at the specified MetaSAC.

Parameters:

metaSacEndpoint - The URL of the endpoint of the MetaSAC where the new SAC is to be created.

sacName - The name that the new SAC should be given.

sacMetadataXml - The metadata to describe the new SAC. This must be in RDF XML format.

Returns:

A String containing the URL of the created SAC.

Throws:

SacClientException - if anything goes wrong, with an explanation of the problem in the exception message.

createSac

java.lang.String createSac(java.lang.String metaSacEndpoint,
                           java.lang.String sacName,
                           java.lang.String sacMetadata,
                           java.lang.String mimeType)
                           throws SacClientException

MetaSAC method to create a new SAC at the specified MetaSAC.

Parameters:

metaSacEndpoint - The URL of the endpoint of the MetaSAC where the new SAC is to be created.

sacName - The name that the new SAC should be given.

sacMetadata - The metadata to describe the new SAC. This must be in the format described by the mimeType parameter.

mimeType - The type of the supplied SAC metadata. This must be one of SacClient.RDF_XML_CONTENT, SacClient.RDF_TEXT_CONTENT, SacClient.TURTLE_CONTENT

Returns:

A String containing the URL of the created SAC.

Throws:

SacClientException - if anything goes wrong, with an explanation of the problem in the exception message.

getSacMetadata

java.lang.String getSacMetadata(java.lang.String sacEndpoint)
                                throws SacClientException

SAC method to retrieve any metadata associated with the SAC. Returns the metadata in RDF XML format.

Parameters:

sacEndpoint - The URL of the SAC whose metadata is to be retrieved.

Returns:

A String containing the SAC Metadata in RDF XML format.

Throws:

SacClientException - if anything goes wrong, with an explanation of the problem in the exception message.

getSacMetadata

java.lang.String getSacMetadata(java.lang.String sacEndpoint,
                                java.lang.String mimeType)
                                throws SacClientException

SAC method to retrieve any metadata associated with the SAC. Returns the metadata in the requested format.

Parameters:

sacEndpoint - The URL of the SAC whose metadata is to be retrieved.

mimeType - The type of the supplied SAC metadata. This must be one of SacClient.RDF_XML_CONTENT, SacClient.RDF_TEXT_CONTENT, SacClient.TURTLE_CONTENT

Returns:

A String containing the SAC Metadata in the requested format.

Throws:

SacClientException - if anything goes wrong, with an explanation of the problem in the exception message.

getSacMetadataAsResource

Resource getSacMetadataAsResource(java.lang.String sacEndpoint)
                                  throws SacClientException

SAC method to retrieve any metadata associated with the SAC. Returns the metadata in Jena Resource format.

Parameters:

sacEndpoint - The URL of the SAC whose metadata is to be retrieved.

Returns:

A Jena Resource containing the SAC Metadata.

Throws:

SacClientException - if anything goes wrong, with an explanation of the problem in the exception message.

getSacContent

java.lang.String getSacContent(java.lang.String sacEndpoint)
                               throws SacClientException

SAC method to retrieve the content of a SAC. Returns the content in RDF XML format.

Parameters:

sacEndpoint - The URL of the SAC whose content is to be retrieved.

Returns:

A String containing the entire SAC contents in RDF XML format.

Throws:

SacClientException - if anything goes wrong, with an explanation of the problem in the exception message.

getSacContent

java.lang.String getSacContent(java.lang.String sacEndpoint,
                               java.lang.String mimeType)
                               throws SacClientException

SAC method to retrieve the content of a SAC. Returns the content in the requested format.

Parameters:

sacEndpoint - The URL of the SAC whose content is to be retrieved.

mimeType - The type of the supplied SAC content. This must be one of SacClient.RDF_XML_CONTENT, SacClient.RDF_TEXT_CONTENT, SacClient.TURTLE_CONTENT

Returns:

A String containing the entire SAC contents in the requested format.

Throws:

SacClientException - if anything goes wrong, with an explanation of the problem in the exception message.

getSacContentAsResource

Resource getSacContentAsResource(java.lang.String sacEndpoint)
                                 throws SacClientException

SAC method to retrieve the content of a SAC. Returns the content in Jena Resource format.

Parameters:

sacEndpoint - The URL of the SAC whose content is to be retrieved.

Returns:

A Jena Resource containing the entire SAC contents.

Throws:

SacClientException - if anything goes wrong, with an explanation of the problem in the exception message.

addClaim

java.lang.String addClaim(java.lang.String sacEndpoint,
                          java.lang.String claimXmlString,
                          java.lang.String mimeType)
                          throws SacClientException

SAC method to add a new claim to a SAC. Returns the ID of the created claim (a URI by which the claim can be retrieved).

Parameters:

sacEndpoint - The URL of the SAC whose metadata is to be retrieved.

claimXmlString - The claim to be added to the SAC

mimeType - The type of the supplied claim This must be one of SacClient.RDF_XML_CONTENT, SacClient.RDF_TEXT_CONTENT, SacClient.TURTLE_CONTENT

Returns:

A String containing the URL of the created claim.

Throws:

SacClientException - if anything goes wrong, with an explanation of the problem in the exception message.

replaceClaim

void replaceClaim(java.lang.String claimID,
                  java.lang.String claimXmlString,
                  java.lang.String mimeType)
                  throws SacClientException

SAC method to replace a pre-existing claim. Returns the ID of the created claim (a URL by which the claim can be retrieved).

Parameters:

claimID - The ID (a URL) of the claim to be replaced.

claimXmlString - The claim to be added to the SAC

mimeType - The type of the supplied claim This must be one of SacClient.RDF_XML_CONTENT, SacClient.RDF_TEXT_CONTENT, SacClient.TURTLE_CONTENT

Throws:

SacClientException - if the claim to be replaced does not exist, or if anything else goes wrong, with an explanation of the problem in the exception message.

getClaim

java.lang.String getClaim(java.lang.String claimID)
                          throws SacClientException

SAC method to retrieve the claim at the specified URL. Returns the claim in RDF XML format.

Parameters:

claimID - The ID (a URL) of the claim to be retrieved.

Returns:

A String containing the retrieved claim in RDF XML format.

Throws:

SacClientException - if anything goes wrong, with an explanation of the problem in the exception message.

getClaim

java.lang.String getClaim(java.lang.String claimID,
                          java.lang.String mimeType)
                          throws SacClientException

SAC method to retrieve the claim at the specified URL. Returns the claim in the requested format.

Parameters:

mimeType - The desired format of the returned claim. This must be one of SacClient.RDF_XML_CONTENT, SacClient.RDF_TEXT_CONTENT, SacClient.TURTLE_CONTENT

Returns:

A String containing the URL of the created claim.

Throws:

SacClientException - if anything goes wrong, with an explanation of the problem in the exception message.

getClaimAsResource

Resource getClaimAsResource(java.lang.String claimID)
                            throws SacClientException

SAC method to retrieve the claim at the specified URL. Returns the claim as a Jena Resource.

Parameters:

claimID - The ID (a URL) of the claim to be retrieved.

Returns:

A Jena Resource containing the retrieved claim.

Throws:

SacClientException - if anything goes wrong, with an explanation of the problem in the exception message.

deleteClaim

void deleteClaim(java.lang.String claimID)
                 throws SacClientException

SAC method to delete the claim at the specified URL. This method does NOT fail if the claim does not exist.

Parameters:

claimID - The ID (a URL) of the claim to be deleted.

Throws:

SacClientException - if anything goes wrong, with an explanation of the problem in the exception message.

runQuery

java.lang.String runQuery(java.lang.String sacEndpoint,
                          java.lang.String sparql,
                          java.lang.String mimeType)
                          throws SacClientException

SAC method to run a SPARQL query against the SAC at the specified URL, and return the results of this query in the specified format.

Parameters:

sacEndpoint - The URL of the endpoint of the SAC to be queried.

mimeType - The desired return type of the results. If the query is a Construct or Describe query, this must be one of SacClient.RDF_XML_CONTENT, SacClient.RDF_TEXT_CONTENT, SacClient.TURTLE_CONTENT. If the query is a Select query, this must be one of SacClient.TEXT_CONTENT, SacClient.SPARQL_RESULTS_CONTENT, SacClient.CSV_CONTENT, SacClient.TSV_CONTENT. If the query is an Ask query, this must be one of SacClient.TEXT_CONTENT, SacClient.SPARQL_RESULTS_CONTENT,

Returns:

A String containing the query results in the requested format.

Throws:

SacClientException - if anything goes wrong, with an explanation of the problem in the exception message.

allowDelegationFrom

void allowDelegationFrom(java.lang.String sacEndpoint,
                         java.lang.String fromSacEndpoint)
                         throws SacClientException

SAC administration method to enable query forwarding (delegation) to be accepted from a given SAC.

Parameters:

sacEndpoint - The URL of the endpoint of the SAC to be administered.

fromSacEndpoint - The URL of the endpoint of the SAC from which delegation is to be accepted.

Throws:

SacClientException - if anything goes wrong, with an explanation of the problem in the exception message.

denyDelegationFrom

void denyDelegationFrom(java.lang.String sacEndpoint,
                        java.lang.String fromSacEndpoint)
                        throws SacClientException

SAC administration method to prevent query forwarding (delegation) from being accepted from a given SAC.

Parameters:

sacEndpoint - The URL of the endpoint of the SAC to be administered.

fromSacEndpoint - The URL of the endpoint of the SAC from which delegation is to be rejected.

Throws:

SacClientException - if anything goes wrong, with an explanation of the problem in the exception message.

addDelegationTo

void addDelegationTo(java.lang.String sacEndpoint,
                     java.lang.String toSacEndpoint)
                     throws SacClientException

SAC administration method to enable query forwarding (delegation) to a given SAC.

Parameters:

sacEndpoint - The URL of the endpoint of the SAC to be administered.

toSacEndpoint - The URL of the endpoint of the SAC to be delegated to.

Throws:

SacClientException - if anything goes wrong, with an explanation of the problem in the exception message.

dropDelegationTo

void dropDelegationTo(java.lang.String sacEndpoint,
                      java.lang.String toSacEndpoint)
                      throws SacClientException

SAC administration method to disable query forwarding (delegation) to a given SAC.

Parameters:

sacEndpoint - The URL of the endpoint of the SAC to be administered.

toSacEndpoint - The URL of the endpoint of the SAC not to be delegated to.

Throws:

SacClientException - if anything goes wrong, with an explanation of the problem in the exception message.