D1Node (DataONE Java Client Library 1.3.0-SNAPSHOT API)

java.lang.Object
- org.dataone.client.D1Node

Direct Known Subclasses:

CNode, MNode
```
public abstract class D1Node
extends Object
```
An abstract node class that contains base functionality shared between Coordinating Node and Member Node implementations. Various methods may set their own timeouts by use of Settings.Configuration properties or by calling setDefaultSoTimeout. Settings.Configuration properties override any value of the DefaultSoTimeout. Timeouts are always represented in milliseconds timeout properties recognized: D1Client.D1Node.listObjects.timeout D1Client.D1Node.getLogRecords.timeout D1Client.D1Node.get.timeout D1Client.D1Node.getSystemMetadata.timeout

Field Summary

Fields
Modifier and Type	Field and Description
`protected static org.apache.commons.logging.Log`	`log`
`protected Session`	`session` this represents the session to be used for establishing the SSL connection

Constructor Summary

Constructors
Constructor and Description
`D1Node()` Deprecated.
`D1Node(String nodeBaseServiceUrl)` Constructor to create a new instance.
`D1Node(String nodeBaseServiceUrl, Session session)` Constructor to create a new instance.

Method Summary

Methods
Modifier and Type	Method and Description
`Identifier`	`archive(Identifier pid)`
`Identifier`	`archive(Session session, Identifier pid)` sets the archived flag to true on an MN or CN
`Identifier`	`delete(Identifier pid)`
`Identifier`	`delete(Session session, Identifier pid)`
`DescribeResponse`	`describe(Identifier pid)`
`DescribeResponse`	`describe(Session session, Identifier pid)`
`protected <T> T`	`deserializeServiceType(Class<T> domainClass, InputStream is)` deserialize an object of type from the inputstream This is a wrapper method of the standard common Unmarshalling method that recasts exceptions to ServiceFailure
`Identifier`	`generateIdentifier(Session session, String scheme, String fragment)`
`Identifier`	`generateIdentifier(String scheme, String fragment)`
`InputStream`	`get(Identifier pid)` Get the resource with the specified pid.
`InputStream`	`get(Session session, Identifier pid)` Get the resource with the specified pid.
`Checksum`	`getChecksum(Identifier pid, String checksumAlgorithm)`
`Checksum`	`getChecksum(Session session, Identifier pid, String checksumAlgorithm)` This method can handle both the MN and CN method, although the CN overriding method will need to recast the InvalidRequest exception and use 'null' for the checksumAlgorithm param
`Integer`	`getDefaultSoTimeout()`
`String`	`getLatestRequestUrl()` Useful for debugging to see what the last call was
`Log`	`getLogRecords()`
`Log`	`getLogRecords(Date fromDate, Date toDate, Event event, String pidFilter, Integer start, Integer count)`
`Log`	`getLogRecords(Session session)`
`Log`	`getLogRecords(Session session, Date fromDate, Date toDate, Event event, String pidFilter, Integer start, Integer count)`
`String`	`getNodeBaseServiceUrl()` Retrieve the service URL for this node.
`String`	`getNodeId()`
`QueryEngineDescription`	`getQueryEngineDescription(String queryEngine)`
`SystemMetadata`	`getSystemMetadata(Identifier pid)` Get the system metadata from a resource with the specified guid.
`SystemMetadata`	`getSystemMetadata(Identifier pid, boolean useSystemMetadataCache)` Get the system metadata from a resource with the specified guid, potentially using the local system metadata cache if specified to do so.
`SystemMetadata`	`getSystemMetadata(Session session, Identifier pid)` Get the system metadata from a resource with the specified guid.
`SystemMetadata`	`getSystemMetadata(Session session, Identifier pid, boolean useSystemMetadataCache)` Get the system metadata from a resource with the specified guid, potentially using the local system metadata cache if specified to do so.
`boolean`	`isAuthorized(Identifier pid, Permission action)`
`boolean`	`isAuthorized(Session session, Identifier pid, Permission action)`
`ObjectList`	`listObjects()` see DataONE API Reference
`ObjectList`	`listObjects(Date fromDate, Date toDate, ObjectFormatIdentifier formatid, Boolean replicaStatus, Integer start, Integer count)`
`ObjectList`	`listObjects(Session session)`
`ObjectList`	`listObjects(Session session, Date fromDate, Date toDate, ObjectFormatIdentifier formatid, Boolean replicaStatus, Integer start, Integer count)`
`QueryEngineList`	`listQueryEngines()`
`Date`	`ping()`
`InputStream`	`query(String queryEngine, D1Url queryUrlElements)` A convenience method for building the query going to the queryEngine.
`InputStream`	`query(String queryEngine, String encodedQuery)` As with the sister query() method that takes a D1Url, the contents of encodedQuery will be joined to the url with as follows: /{queryEngine}/{encodedQuery} Note: Users will need to provide the '?' where appropriate to mark the beginning of the url-query portion.
`protected static ServiceFailure`	`recastClientSideExceptionToServiceFailure(Exception e)` A helper function to preserve the stackTrace when catching one error and throwing a new one.
`protected static ServiceFailure`	`recastDataONEExceptionToServiceFailure(BaseException be)` A helper function for recasting DataONE exceptions to ServiceFailures while preserving the detail code and TraceDetails.
`void`	`setDefaultSoTimeout(Integer defaultSoTimeout)`
`protected void`	`setLatestRequestUrl(String url)`
`void`	`setNodeBaseServiceUrl(String nodeBaseServiceUrl)` Set the service URL for this node.
`void`	`setNodeId(String nodeId)`

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail
- log
```
protected static org.apache.commons.logging.Log log
```
- session
```
protected Session session
```
  this represents the session to be used for establishing the SSL connection

Constructor Detail
- D1Node
```
public D1Node(String nodeBaseServiceUrl,
      Session session)
```
  Constructor to create a new instance.
- D1Node
```
public D1Node(String nodeBaseServiceUrl)
```
  Constructor to create a new instance.
- D1Node
```
@Deprecated
public D1Node()
```
  Deprecated.
  
  default constructor needed by some clients. This constructor will probably go away so don't depend on it. Use public D1Node(String nodeBaseServiceUrl) instead.

Method Detail

getLatestRequestUrl
```
public String getLatestRequestUrl()
```
Useful for debugging to see what the last call was

Returns:

setLatestRequestUrl

protected void setLatestRequestUrl(String url)

getNodeBaseServiceUrl
```
public String getNodeBaseServiceUrl()
```
Retrieve the service URL for this node. The service URL can be used with knowledge of the DataONE REST API to construct endpoints for each of the DataONE REST services that are available on the node.

Returns:
String representing the service URL

setNodeBaseServiceUrl
```
public void setNodeBaseServiceUrl(String nodeBaseServiceUrl)
```
Set the service URL for this node. The service URL can be used with knowledge of the DataONE REST API to construct endpoints for each of the DataONE REST services that are available on the node.

Parameters:
nodeBaseServiceUrl - String representing the service URL

getNodeId
```
public String getNodeId()
```
Returns:
the nodeId

setNodeId
```
public void setNodeId(String nodeId)
```
Parameters:
nodeId - the nodeId to set

ping

public Date ping()
          throws NotImplemented,
                 ServiceFailure,
                 InsufficientResources

Throws:: NotImplemented; ServiceFailure; InsufficientResources

listObjects

public ObjectList listObjects()
                       throws InvalidRequest,
                              InvalidToken,
                              NotAuthorized,
                              NotImplemented,
                              ServiceFailure

see DataONE API Reference

Throws:: InvalidRequest; InvalidToken; NotAuthorized; NotImplemented; ServiceFailure

listObjects

public ObjectList listObjects(Session session)
                       throws InvalidRequest,
                              InvalidToken,
                              NotAuthorized,
                              NotImplemented,
                              ServiceFailure

Throws:: InvalidRequest; InvalidToken; NotAuthorized; NotImplemented; ServiceFailure

listObjects

public ObjectList listObjects(Date fromDate,
                     Date toDate,
                     ObjectFormatIdentifier formatid,
                     Boolean replicaStatus,
                     Integer start,
                     Integer count)
                       throws InvalidRequest,
                              InvalidToken,
                              NotAuthorized,
                              NotImplemented,
                              ServiceFailure

Throws:: InvalidRequest; InvalidToken; NotAuthorized; NotImplemented; ServiceFailure

listObjects

public ObjectList listObjects(Session session,
                     Date fromDate,
                     Date toDate,
                     ObjectFormatIdentifier formatid,
                     Boolean replicaStatus,
                     Integer start,
                     Integer count)
                       throws InvalidRequest,
                              InvalidToken,
                              NotAuthorized,
                              NotImplemented,
                              ServiceFailure

Throws:: InvalidRequest; InvalidToken; NotAuthorized; NotImplemented; ServiceFailure

getLogRecords

public Log getLogRecords()
                  throws InvalidToken,
                         InvalidRequest,
                         ServiceFailure,
                         NotAuthorized,
                         NotImplemented,
                         InsufficientResources

Throws:: InvalidToken; InvalidRequest; ServiceFailure; NotAuthorized; NotImplemented; InsufficientResources

getLogRecords

public Log getLogRecords(Session session)
                  throws InvalidToken,
                         InvalidRequest,
                         ServiceFailure,
                         NotAuthorized,
                         NotImplemented,
                         InsufficientResources

Throws:: InvalidToken; InvalidRequest; ServiceFailure; NotAuthorized; NotImplemented; InsufficientResources

getLogRecords

public Log getLogRecords(Date fromDate,
                Date toDate,
                Event event,
                String pidFilter,
                Integer start,
                Integer count)
                  throws InvalidToken,
                         InvalidRequest,
                         ServiceFailure,
                         NotAuthorized,
                         NotImplemented,
                         InsufficientResources

Throws:: InvalidToken; InvalidRequest; ServiceFailure; NotAuthorized; NotImplemented; InsufficientResources

getLogRecords

public Log getLogRecords(Session session,
                Date fromDate,
                Date toDate,
                Event event,
                String pidFilter,
                Integer start,
                Integer count)
                  throws InvalidToken,
                         InvalidRequest,
                         ServiceFailure,
                         NotAuthorized,
                         NotImplemented,
                         InsufficientResources

Throws:: InvalidToken; InvalidRequest; ServiceFailure; NotAuthorized; NotImplemented; InsufficientResources

get
```
public InputStream get(Identifier pid)
                throws InvalidToken,
                       ServiceFailure,
                       NotAuthorized,
                       NotFound,
                       NotImplemented,
                       InsufficientResources
```
Get the resource with the specified pid. Used by both the CNode and MNode subclasses. A LocalCache is used to cache objects in memory and in a local disk cache if the "D1Client.useLocalCache" configuration property was set to true when the D1Node was created. Otherwise InputStream is the Java native version of D1's OctetStream

Throws:

InvalidToken

ServiceFailure

NotAuthorized

NotFound

NotImplemented

InsufficientResources
See Also:
see DataONE API Reference (MemberNode API), see DataONE API Reference (CoordinatingNode API)

get
```
public InputStream get(Session session,
              Identifier pid)
                throws InvalidToken,
                       ServiceFailure,
                       NotAuthorized,
                       NotFound,
                       NotImplemented,
                       InsufficientResources
```
Get the resource with the specified pid. Used by both the CNode and MNode subclasses. A LocalCache is used to cache objects in memory and in a local disk cache if the "D1Client.useLocalCache" configuration property was set to true when the D1Node was created. Otherwise InputStream is the Java native version of D1's OctetStream

Throws:

InvalidToken

ServiceFailure

NotAuthorized

NotFound

NotImplemented

InsufficientResources
See Also:
see DataONE API Reference (MemberNode API), see DataONE API Reference (CoordinatingNode API)

getSystemMetadata
```
public SystemMetadata getSystemMetadata(Identifier pid)
                                 throws InvalidToken,
                                        ServiceFailure,
                                        NotAuthorized,
                                        NotFound,
                                        NotImplemented
```
Get the system metadata from a resource with the specified guid. Used by both the CNode and MNode implementations. Note that this method defaults to not using the local system metadata cache provided by the client, as SystemMetadata is mutable and so caching can lead to issues. In specific cases where a client wants to utilize the same system metadata in rapid succession, it may make sense to temporarily use the local cache by calling @see #getSystemMetadata(Session, Identifier, boolean).

Throws:

InvalidToken

ServiceFailure

NotAuthorized

NotFound

NotImplemented
See Also:
DataONE API Reference (MemberNode API), DataONE API Reference (CoordinatingNode API)

getSystemMetadata
```
public SystemMetadata getSystemMetadata(Identifier pid,
                               boolean useSystemMetadataCache)
                                 throws InvalidToken,
                                        ServiceFailure,
                                        NotAuthorized,
                                        NotFound,
                                        NotImplemented
```
Get the system metadata from a resource with the specified guid, potentially using the local system metadata cache if specified to do so. Used by both the CNode and MNode implementations. Because SystemMetadata is mutable, caching can lead to currency issues. In specific cases where a client wants to utilize the same system metadata in rapid succession, it may make sense to temporarily use the local cache by setting useSystemMetadadataCache to true.

Throws:

InvalidToken

ServiceFailure

NotAuthorized

NotFound

NotImplemented
See Also:
DataONE API Reference (MemberNode API), DataONE API Reference (CoordinatingNode API)

getSystemMetadata
```
public SystemMetadata getSystemMetadata(Session session,
                               Identifier pid)
                                 throws InvalidToken,
                                        ServiceFailure,
                                        NotAuthorized,
                                        NotFound,
                                        NotImplemented
```
Get the system metadata from a resource with the specified guid. Used by both the CNode and MNode implementations. Note that this method defaults to not using the local system metadata cache provided by the client, as SystemMetadata is mutable and so caching can lead to issues. In specific cases where a client wants to utilize the same system metadata in rapid succession, it may make sense to temporarily use the local cache by calling @see #getSystemMetadata(Session, Identifier, boolean).

Throws:

InvalidToken

ServiceFailure

NotAuthorized

NotFound

NotImplemented
See Also:
DataONE API Reference (MemberNode API), DataONE API Reference (CoordinatingNode API)

getSystemMetadata

public SystemMetadata getSystemMetadata(Session session,
                               Identifier pid,
                               boolean useSystemMetadataCache)
                                 throws InvalidToken,
                                        ServiceFailure,
                                        NotAuthorized,
                                        NotFound,
                                        NotImplemented

Get the system metadata from a resource with the specified guid, potentially using the local system metadata cache if specified to do so. Used by both the CNode and MNode implementations. Because SystemMetadata is mutable, caching can lead to currency issues. In specific cases where a client wants to utilize the same system metadata in rapid succession, it may make sense to temporarily use the local cache by setting useSystemMetadadataCache to true.

Throws:: InvalidToken; ServiceFailure; NotAuthorized; NotFound; NotImplemented
See Also:: DataONE API Reference (MemberNode API), DataONE API Reference (CoordinatingNode API)

describe

public DescribeResponse describe(Identifier pid)
                          throws InvalidToken,
                                 NotAuthorized,
                                 NotImplemented,
                                 ServiceFailure,
                                 NotFound

Throws:: InvalidToken; NotAuthorized; NotImplemented; ServiceFailure; NotFound

describe

public DescribeResponse describe(Session session,
                        Identifier pid)
                          throws InvalidToken,
                                 NotAuthorized,
                                 NotImplemented,
                                 ServiceFailure,
                                 NotFound

Throws:: InvalidToken; NotAuthorized; NotImplemented; ServiceFailure; NotFound

getChecksum

public Checksum getChecksum(Identifier pid,
                   String checksumAlgorithm)
                     throws InvalidRequest,
                            InvalidToken,
                            NotAuthorized,
                            NotImplemented,
                            ServiceFailure,
                            NotFound

Throws:: InvalidRequest; InvalidToken; NotAuthorized; NotImplemented; ServiceFailure; NotFound

getChecksum

public Checksum getChecksum(Session session,
                   Identifier pid,
                   String checksumAlgorithm)
                     throws InvalidRequest,
                            InvalidToken,
                            NotAuthorized,
                            NotImplemented,
                            ServiceFailure,
                            NotFound

This method can handle both the MN and CN method, although the CN overriding method will need to recast the InvalidRequest exception and use 'null' for the checksumAlgorithm param

Parameters:: session -; pid -; checksumAlgorithm - - for MN implementations only
Returns:
Throws:: InvalidRequest - - for MN implementations only; InvalidToken; NotAuthorized; NotImplemented; ServiceFailure; NotFound

isAuthorized

public boolean isAuthorized(Identifier pid,
                   Permission action)
                     throws ServiceFailure,
                            InvalidRequest,
                            InvalidToken,
                            NotFound,
                            NotAuthorized,
                            NotImplemented

Throws:: ServiceFailure; InvalidRequest; InvalidToken; NotFound; NotAuthorized; NotImplemented

isAuthorized

public boolean isAuthorized(Session session,
                   Identifier pid,
                   Permission action)
                     throws ServiceFailure,
                            InvalidRequest,
                            InvalidToken,
                            NotFound,
                            NotAuthorized,
                            NotImplemented

Throws:: ServiceFailure; InvalidRequest; InvalidToken; NotFound; NotAuthorized; NotImplemented

generateIdentifier

public Identifier generateIdentifier(String scheme,
                            String fragment)
                              throws InvalidToken,
                                     ServiceFailure,
                                     NotAuthorized,
                                     NotImplemented,
                                     InvalidRequest

Throws:: InvalidToken; ServiceFailure; NotAuthorized; NotImplemented; InvalidRequest

generateIdentifier

public Identifier generateIdentifier(Session session,
                            String scheme,
                            String fragment)
                              throws InvalidToken,
                                     ServiceFailure,
                                     NotAuthorized,
                                     NotImplemented,
                                     InvalidRequest

Throws:: InvalidToken; ServiceFailure; NotAuthorized; NotImplemented; InvalidRequest

delete

public Identifier delete(Identifier pid)
                  throws InvalidToken,
                         ServiceFailure,
                         NotAuthorized,
                         NotFound,
                         NotImplemented

Throws:: InvalidToken; ServiceFailure; NotAuthorized; NotFound; NotImplemented

delete

public Identifier delete(Session session,
                Identifier pid)
                  throws InvalidToken,
                         ServiceFailure,
                         NotAuthorized,
                         NotFound,
                         NotImplemented

Throws:: InvalidToken; ServiceFailure; NotAuthorized; NotFound; NotImplemented

query
```
public InputStream query(String queryEngine,
                D1Url queryUrlElements)
                  throws InvalidToken,
                         ServiceFailure,
                         NotAuthorized,
                         InvalidRequest,
                         NotImplemented,
                         NotFound
```
A convenience method for building the query going to the queryEngine. A D1Url will build the portion of the url needed and properly url-encode any unsafe characters. The caller is responsible for encoding/escaping any special characters required by the queryEngine, but not for providing any url reserved characters ('/' or '?') that join path or query elements. As with the sister query() method that takes an encoded string, the contents will be joined to the url with as follows: /{queryEngine}/{queryUrlElements}

Parameters:
queryEngine -
queryUrlElements - a D1Url object that contains the necessary query bits

Returns:

Throws:

InvalidToken

ServiceFailure

NotAuthorized

InvalidRequest

NotImplemented

NotFound

query
```
public InputStream query(String queryEngine,
                String encodedQuery)
                  throws InvalidToken,
                         ServiceFailure,
                         NotAuthorized,
                         InvalidRequest,
                         NotImplemented,
                         NotFound
```
As with the sister query() method that takes a D1Url, the contents of encodedQuery will be joined to the url with as follows: /{queryEngine}/{encodedQuery} Note: Users will need to provide the '?' where appropriate to mark the beginning of the url-query portion. (for example, solr queries are entirely contained in the query portion of a url, so users need the first character of the provided encodedQuery to be a '?')

Parameters:
queryEngine -
encodedQuery -

Returns:

Throws:

InvalidToken

ServiceFailure

NotAuthorized

InvalidRequest

NotImplemented

NotFound

getQueryEngineDescription

public QueryEngineDescription getQueryEngineDescription(String queryEngine)
                                                 throws InvalidToken,
                                                        ServiceFailure,
                                                        NotAuthorized,
                                                        NotImplemented,
                                                        NotFound

Throws:: InvalidToken; ServiceFailure; NotAuthorized; NotImplemented; NotFound

listQueryEngines

public QueryEngineList listQueryEngines()
                                 throws InvalidToken,
                                        ServiceFailure,
                                        NotAuthorized,
                                        NotImplemented

Throws:: InvalidToken; ServiceFailure; NotAuthorized; NotImplemented

recastClientSideExceptionToServiceFailure
```
protected static ServiceFailure recastClientSideExceptionToServiceFailure(Exception e)
```
A helper function to preserve the stackTrace when catching one error and throwing a new one. Also has some descriptive text which makes it clientSide specific

Parameters:
e -

Returns:

recastDataONEExceptionToServiceFailure
```
protected static ServiceFailure recastDataONEExceptionToServiceFailure(BaseException be)
```
A helper function for recasting DataONE exceptions to ServiceFailures while preserving the detail code and TraceDetails.

Parameters:
be - - BaseException subclass to be recast

Returns:
ServiceFailure

deserializeServiceType
```
protected <T> T deserializeServiceType(Class<T> domainClass,
                           InputStream is)
                            throws ServiceFailure
```
deserialize an object of type from the inputstream This is a wrapper method of the standard common Unmarshalling method that recasts exceptions to ServiceFailure

Parameters:
type - the class of the object to serialize (i.e. SystemMetadata.class)
is - the stream to deserialize from

Throws:

ServiceFailure

getDefaultSoTimeout
```
public Integer getDefaultSoTimeout()
```

setDefaultSoTimeout

public void setDefaultSoTimeout(Integer defaultSoTimeout)

Class D1Node

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

log

session

Constructor Detail

D1Node

D1Node

D1Node

Method Detail

getLatestRequestUrl

setLatestRequestUrl

getNodeBaseServiceUrl

setNodeBaseServiceUrl

getNodeId

setNodeId

ping

listObjects

listObjects

listObjects

listObjects

getLogRecords

getLogRecords

getLogRecords

getLogRecords

get

get

getSystemMetadata

getSystemMetadata

getSystemMetadata

getSystemMetadata

describe

describe

getChecksum

getChecksum

isAuthorized

isAuthorized

generateIdentifier

generateIdentifier

archive

archive

delete

delete

query

query

getQueryEngineDescription

listQueryEngines

recastClientSideExceptionToServiceFailure

recastDataONEExceptionToServiceFailure

deserializeServiceType

getDefaultSoTimeout

setDefaultSoTimeout