org.dlese.dpc.services.dds.toolkit
Class DDSServicesToolkit

java.lang.Object
  org.dlese.dpc.services.dds.toolkit.DDSServicesToolkit

public class DDSServicesToolkit
extends Object

Toolkit for working with DDS repository Search and Update Web Services (DDSWS and DDSUpdateWS) for read and write operations. All methods use only local variables and are thread safe but are not synchronized. See DDSWS documentation and DDSUpdateWS documentation

Author:

John Weatherley

Field Summary

static int	SORT_ORDER_ASCENDING Indicates the optional sort order for search results should be ascending
static int	SORT_ORDER_DESCENDING Indicates the optional sort order for search results should be descending
static int	SORT_ORDER_NO_SORT Indicates no sorting should be applied to search results

Constructor Summary

DDSServicesToolkit(String ddsServicesUrl, String clientName)
Constructor for the DDSServicesToolkit object

Method Summary

protected String[]	checkForErrorResponseDDSUpdateWS(Document ddsupdateResponse) Checks for the existance of an error response from a DDS update service request (DDSUpdateWS).
protected String[]	checkForErrorResponseDDSWS(Document ddswsResponse) Checks for the existance of an error response from a DDS service request (DDSWS).
DDSServicesResponse	deleteRecord(String recordId) Deletes a record from a DDS repository.
protected static String	getDateStamp() Return a string for the current time and date, sutiable for display in log files and output to standout:
String	getIndexVersion() Gets the index version, which can be useful to determine if a service response cache needs to be updated.
DDSServicesResponse	getRecord(String id, String showRelation, String xmlFormat, Map additionalRequestParams, boolean soAllRecords, boolean localizeXml) Performs a GetRecord request from a DDSWS repository.
boolean	hasCollection(String collectionKey, String xmlFormat) Determines whether the given collection is in this DDS repository.
boolean	hasRecord(String id, String xmlFormat) Determines whether the given record is in this DDS repository.
DDSServicesResponse	listCollections(boolean localizeXml) Performs a ListCollections request from a DDSWS repository.
DDSServicesResponse	listFields(boolean localizeXml) Performs a ListFields request from a DDSWS repository.
DDSServicesResponse	listTerms(String[] fields, boolean localizeXml) Performs a ListTerms request from a DDSWS repository.
DDSServicesResponse	putCollection(String collectionKey, String xmlFormat, String collectionName, String collectionDescription) Puts a collection into a DDS repository.
Document	putRecord(String recordId, String recordXml, String collectionKey, String xmlFormat) Puts a record into a DDS repository.
DDSServicesResponse	search(String query, String xmlFormat, int startOffset, int numReturns, String sortByField, int sortOrder, String showRelation, Map additionalRequestParams, boolean soAllRecords, boolean localizeXml) Performs a Search request from a DDSWS repository.
DDSServicesResponse	serviceInfo(boolean localizeXml) Performs a ServiceInfo request from a DDSWS repository.
static void	setDebug(boolean db) Sets the debug attribute of the object

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

SORT_ORDER_ASCENDING

public static int SORT_ORDER_ASCENDING

Indicates the optional sort order for search results should be ascending

SORT_ORDER_DESCENDING

public static int SORT_ORDER_DESCENDING

Indicates the optional sort order for search results should be descending

SORT_ORDER_NO_SORT

public static int SORT_ORDER_NO_SORT

Indicates no sorting should be applied to search results

Constructor Detail

DDSServicesToolkit

public DDSServicesToolkit(String ddsServicesUrl,
                          String clientName)

Constructor for the DDSServicesToolkit object

Parameters:

ddsServicesUrl - Common baseUrl for DDS services, for example http://www.dlese.org/dds/services/

clientName - The client name, or null to send none

Method Detail

getRecord

public DDSServicesResponse getRecord(String id,
                                     String showRelation,
                                     String xmlFormat,
                                     Map additionalRequestParams,
                                     boolean soAllRecords,
                                     boolean localizeXml)
                              throws DDSServiceErrorResponseException,
                                     Exception

Performs a GetRecord request from a DDSWS repository.

Parameters:

id - Record ID

showRelation - The relation data to include in the response for example isAnnotatedBy, or null for none

xmlFormat - The XML format to return, or null for native format

additionalRequestParams - A Map that contains param/value pairs. Values must be of type String to indicate a single value, or a String [] to indicate multiple values. Map may be null for none.

soAllRecords - True to search all records including non-discoverable ones (client must be authorized by IP)

localizeXml - True to localize the response

Returns:

The service response

Throws:

DDSServiceErrorResponseException - Standard service error if one was returned

Exception - If other error occurs

hasRecord

public boolean hasRecord(String id,
                         String xmlFormat)
                  throws DDSServiceErrorResponseException,
                         Exception

Determines whether the given record is in this DDS repository. If a format is specified, then also determines if the record can be dissiminated in the given format.

Parameters:

id - The record id

xmlFormat - The XML format to check availability for, or null for any/all

Returns:

True if the given record is in the repository

Throws:

DDSServiceErrorResponseException - If service error

Exception - If other error

search

public DDSServicesResponse search(String query,
                                  String xmlFormat,
                                  int startOffset,
                                  int numReturns,
                                  String sortByField,
                                  int sortOrder,
                                  String showRelation,
                                  Map additionalRequestParams,
                                  boolean soAllRecords,
                                  boolean localizeXml)
                           throws DDSServiceErrorResponseException,
                                  Exception

Performs a Search request from a DDSWS repository.

Parameters:

query - The search query, or null

xmlFormat - The xmlFormat for which results must be dissiminated, or null for any/all

startOffset - Starting offset in the returns

numReturns - Number of records to return

showRelation - The relation data to include in the response for example isAnnotatedBy, or null for none

additionalRequestParams - A Map that contains param/value pairs. Values must be of type String to indicate a single value, or a String [] to indicate multiple values. Map may be null for none.

soAllRecords - True to search all records including non-discoverable ones (client must be authorized by IP)

localizeXml - True to localize the response

sortByField - Indicates the search field to sort the results by, or null for none

sortOrder - The sort order to apply (ascending, descending). Ignored if no sortByField has been indicated

Returns:

The service response

Throws:

DDSServiceErrorResponseException - Standard service error if one was returned

Exception - If other error occurs

listCollections

public DDSServicesResponse listCollections(boolean localizeXml)
                                    throws DDSServiceErrorResponseException,
                                           Exception

Performs a ListCollections request from a DDSWS repository.

Parameters:

localizeXml - True to localize the response XML

Returns:

The service response

Throws:

DDSServiceErrorResponseException - Standard service error if one was returned

Exception - If other error occurs

serviceInfo

public DDSServicesResponse serviceInfo(boolean localizeXml)
                                throws DDSServiceErrorResponseException,
                                       Exception

Performs a ServiceInfo request from a DDSWS repository.

Parameters:

localizeXml - True to localize the response XML

Returns:

The service response

Throws:

DDSServiceErrorResponseException - Standard service error if one was returned

Exception - If other error occurs

getIndexVersion

public String getIndexVersion()
                       throws DDSServiceErrorResponseException,
                              Exception

Gets the index version, which can be useful to determine if a service response cache needs to be updated.

Returns:

The indexVersion value

Throws:

DDSServiceErrorResponseException - If DDSServiceErrorResponseException error

Exception - If exception

listFields

public DDSServicesResponse listFields(boolean localizeXml)
                               throws DDSServiceErrorResponseException,
                                      Exception

Performs a ListFields request from a DDSWS repository.

Parameters:

localizeXml - True to localize the response XML

Returns:

The service response

Throws:

DDSServiceErrorResponseException - Standard service error if one was returned

Exception - If other error occurs

listTerms

public DDSServicesResponse listTerms(String[] fields,
                                     boolean localizeXml)
                              throws DDSServiceErrorResponseException,
                                     Exception

Performs a ListTerms request from a DDSWS repository. The request accepts one or more fields to list the terms data for. Note that this request is much less efficient when more than one field is requested.

Parameters:

fields - One or more fields to list terms for

localizeXml - True to localize the response XML

Returns:

The service response

Throws:

DDSServiceErrorResponseException - Standard service error if one was returned

Exception - If other error occurs

hasCollection

public boolean hasCollection(String collectionKey,
                             String xmlFormat)
                      throws DDSServiceErrorResponseException,
                             Exception

Determines whether the given collection is in this DDS repository.

Parameters:

collectionKey - The collection key, for example 'dcc'

xmlFormat - The xml format for this collection, for example 'adn'

Returns:

True if the given collection is in the repository with the given

Throws:

DDSServiceErrorResponseException - If service error

Exception - If other error

checkForErrorResponseDDSWS

protected String[] checkForErrorResponseDDSWS(Document ddswsResponse)

Checks for the existance of an error response from a DDS service request (DDSWS). If no error was recieved, this method returns null, otherwise returns the error code and message.

Parameters:

ddswsResponse - The service response

Returns:

The error code and message [code,message], or null if none

putRecord

public Document putRecord(String recordId,
                          String recordXml,
                          String collectionKey,
                          String xmlFormat)
                   throws DDSServiceErrorResponseException,
                          Exception

Puts a record into a DDS repository.

Parameters:

recordId - recordId

recordXml - recordXml

collectionKey - collectionKey

xmlFormat - xmlFormat

Returns:

The service response

Throws:

Exception - If error

DDSServiceErrorResponseException - Standard service error if one was returned

deleteRecord

public DDSServicesResponse deleteRecord(String recordId)
                                 throws DDSServiceErrorResponseException,
                                        Exception

Deletes a record from a DDS repository.

Parameters:

recordId - recordId

Returns:

The service response

Throws:

DDSServiceErrorResponseException - Standard service error if one was returned

Exception - If other error occurs

putCollection

public DDSServicesResponse putCollection(String collectionKey,
                                         String xmlFormat,
                                         String collectionName,
                                         String collectionDescription)
                                  throws DDSServiceErrorResponseException,
                                         Exception

Puts a collection into a DDS repository.

Parameters:

collectionKey - The collection key, for example 'dcc'

xmlFormat - The xml format, for example 'adn'

collectionName - The name of the collection

collectionDescription - Description of the collection

Returns:

The service response

Throws:

DDSServiceErrorResponseException - Standard service error if one was returned

Exception - If other error occurs

checkForErrorResponseDDSUpdateWS

protected String[] checkForErrorResponseDDSUpdateWS(Document ddsupdateResponse)

Checks for the existance of an error response from a DDS update service request (DDSUpdateWS). If no error was recieved, this method returns null, otherwise returns the error code and message.

Parameters:

ddsupdateResponse - The DDS response

Returns:

The error code and message [code,message], or null if none

getDateStamp

protected static final String getDateStamp()

Return a string for the current time and date, sutiable for display in log files and output to standout:

Returns:

The dateStamp value

setDebug

public static void setDebug(boolean db)

Sets the debug attribute of the object

Parameters:

db - The new debug value