PassClient (pass-client-api 0.7.0 API)

```
public interface PassClient
```
Interface for interactions with PASS database

Author:

Karen Hanson

Method Summary

All Methods Instance Methods Abstract Methods Default Methods
Modifier and Type	Method and Description
`<T extends PassEntity> T`	`createAndReadResource(T modelObj, Class<T> modelClass)` Takes any `PassEntity` and persists it in the database, and returns an updated version of the resource if successful or appropriate exception if not.
`URI`	`createResource(PassEntity modelObj)` Takes any `PassEntity` and persists it in the database, returns the URI if successful or appropriate exception if not.
`void`	`deleteResource(URI uri)` Deletes the entity matching the URI provided
`<T extends PassEntity> Set<URI>`	`findAllByAttribute(Class<T> modelClass, String attribute, Object value)` Retrieves URIs for MULTIPLE MATCHING RECORDS by matching the entity type and filtering by the field specified using the value provided.
`<T extends PassEntity> Set<URI>`	`findAllByAttribute(Class<T> modelClass, String attribute, Object value, int limit, int offset)` Retrieves URIs for MULTIPLE MATCHING RECORDS by matching the entity type and filtering by the field specified using the value provided.
`<T extends PassEntity> Set<URI>`	`findAllByAttributes(Class<T> modelClass, Map<String,Object> attributeValuesMap)` Retrieves URIs for MULTIPLE MATCHING RECORDS by matching the entity type and filtering by the attributes and values specified.
`<T extends PassEntity> Set<URI>`	`findAllByAttributes(Class<T> modelClass, Map<String,Object> attributeValuesMap, int limit, int offset)` Retrieves URIs for MULTIPLE MATCHING RECORDS by matching the entity type and filtering by the attributes and values specified.
`<T extends PassEntity> URI`	`findByAttribute(Class<T> modelClass, String attribute, Object value)` Retrieves URI for a SINGLE RECORD by matching the entity type and filtering by the field specified using the value provided.
`Map<String,Collection<URI>>`	`getIncoming(URI passEntity)` Retrieve inbound links to the repository resource identified by `PassEntity`.
`default <T extends PassEntity> int`	`processAllEntities(Consumer<URI> processor)` Visit all PASS entities
`<T extends PassEntity> int`	`processAllEntities(Consumer<URI> processor, Class<T> modelClass)` Visit all PASS entities in the repository of a given class.
`<T extends PassEntity> T`	`readResource(URI uri, Class<T> modelClass)` Retrieves the entity matching the URI provided, populates the appropriate Java class with its values.
`<T extends PassEntity> T`	`updateAndReadResource(T modelObj, Class<T> modelClass)` Takes any `PassEntity`, and updates the record matching the ID field.
`void`	`updateResource(PassEntity modelObj)` Takes any `PassEntity`, and updates the record matching the ID field.
`URI`	`upload(URI entityUri, InputStream content)` `POST`s the `content` to `entityUri`.
`URI`	`upload(URI entityUri, InputStream content, Map<String,?> params)` `POST`s the supplied `content` to the supplied `entityUri`.

- Method Detail
  - createResource
```
URI createResource(PassEntity modelObj)
```
    Takes any PassEntity and persists it in the database, returns the URI if successful or appropriate exception if not. Note that PassEntities that are being created should have null as their ID, the URI will the the ID field when reading the resource back
    
    Parameters:
    
    modelObj - The entity to be created
    
    Returns:
    
    URI of new record
  - createAndReadResource
```
<T extends PassEntity> T createAndReadResource(T modelObj,
                                               Class<T> modelClass)
```
    Takes any PassEntity and persists it in the database, and returns an updated version of the resource if successful or appropriate exception if not. Note that PassEntities that are being created should have null as their ID; the URI will be present on the returned object.
    
    Type Parameters:
    
    T - PASS entity type
    
    Parameters:
    
    modelObj - the object to be created.
    
    modelClass - The class of PASS entity.
    
    Returns:
    
    an updated version of the resource
  - updateResource
```
void updateResource(PassEntity modelObj)
```
    Takes any PassEntity, and updates the record matching the ID field. Note that if you attempt to update an object that was updated between the readResource and the updateResource, a runtime exception will be thrown. This comparison is based on the value in PassEntity.versionTag. Setting versionTag to null will ignore conflicts and do the update.
    
    Parameters:
    
    modelObj - The object to be updated
  - updateAndReadResource
```
<T extends PassEntity> T updateAndReadResource(T modelObj,
                                               Class<T> modelClass)
```
    Takes any PassEntity, and updates the record matching the ID field. Note that if you attempt to update an object that was updated between the readResource and the updateResource, a runtime exception will be thrown. This comparison is based on the value in PassEntity.versionTag. Setting versionTag to null will ignore conflicts and do the update.
    
    Type Parameters:
    
    T - PASS entity type
    
    Parameters:
    
    modelObj - The entity to be updated
    
    modelClass - The class of the PASS entity.
    
    Returns:
    
    an updated version of the resource
  - deleteResource
```
void deleteResource(URI uri)
```
    Deletes the entity matching the URI provided
    
    Parameters:
    
    uri - the URI of the resource to be deleted.
  - readResource
```
<T extends PassEntity> T readResource(URI uri,
                                      Class<T> modelClass)
```
    Retrieves the entity matching the URI provided, populates the appropriate Java class with its values.
    
    Type Parameters:
    
    T - PASS entity type
    
    Parameters:
    
    uri - The URI of the resource to be read.
    
    modelClass - The class of PASS entity.
    
    Returns:
    
    The pass entity.
  - findByAttribute
```
<T extends PassEntity> URI findByAttribute(Class<T> modelClass,
                                           String attribute,
                                           Object value)
```
    Retrieves URI for a SINGLE RECORD by matching the entity type and filtering by the field specified using the value provided. For example, to find the Grant using the awardNumber:
    For example, to find the Grant using the awardNumber:
```
    String awardNum = "abcdef123";
    URI grantId = findByAttribute(Grant.class, "awardNumber", awardNum);
 
```
    If >1 records are found, a RuntimeException will be thrown. If no records are found it will return null.
    
    The value parameter will be converted to a String for the purpose of searching the index. The value parameter cannot be a Collection. Where the attribute is a multi-valued field, only one value from that field should be provided. For example, if searching on Submission.repositories, a single repository URI should be provided for matching
    Type Parameters:
    
    T - PASS entity type
    
    Parameters:
    
    modelClass - The PASS entity class.
    
    attribute - JSON attribute name.
    
    value - value of the attribute.
    
    Returns:
    
    The matching PASS entity URI.
  - findAllByAttribute
```
<T extends PassEntity> Set<URI> findAllByAttribute(Class<T> modelClass,
                                                   String attribute,
                                                   Object value)
```
    Retrieves URIs for MULTIPLE MATCHING RECORDS by matching the entity type and filtering by the field specified using the value provided.
    For example, to find Deposits using a Repository.id:
```
    URI repositoryId = new URI("https://example.com/fedora/repositories/3");
    Set<URI> entityUris = findByAttribute(Deposit.class, "repository", repositoryId);
  
```
    By default this will return a maximum of 200 matching records, unless the pass.elasticsearch.limit environment variable is set. If there are no matches, it will return an empty list.
    
    The value parameter will be converted to a String for the purpose of searching the index. The value parameter cannot be a Collection. Where the attribute is a multi-valued field, only one value from that field should be provided. For example, if searching on Submission.repositories, a single repository URI should be provided for matching
    Type Parameters:
    
    T - PASS entity type
    
    Parameters:
    
    modelClass - The class of PASS entity.
    
    attribute - JSON attribute name.
    
    value - The value of the PASS attribute.
    
    Returns:
    
    Set of all matching PASS entity URIs.
  - findAllByAttribute
```
<T extends PassEntity> Set<URI> findAllByAttribute(Class<T> modelClass,
                                                   String attribute,
                                                   Object value,
                                                   int limit,
                                                   int offset)
```
    Retrieves URIs for MULTIPLE MATCHING RECORDS by matching the entity type and filtering by the field specified using the value provided.
    For example, to find Deposits using a Repository.id starting from record number 40, retrieving 20 records:
```
   
   URI repositoryId = new URI("https://example.com/fedora/repositories/3");
   Set<URI> entityUris = findByAttribute(Deposit.class, "repository", repositoryId, 20, 40);
 
```
    The number of records will be limited by limit provided, and the offset will be applied to the default sorting. If there are no matches, it will return an empty list. This will override the limit env variable
    
    The value parameter will be converted to a String for the purpose of searching the index. The value parameter cannot be a Collection. Where the attribute is a multi-valued field, only one value from that field should be provided. For example, if searching on Submission.repositories, a single repository URI should be provided for matching
    Type Parameters:
    
    T - PASS entity type
    
    Parameters:
    
    modelClass - The class of PASS entity.
    
    attribute - JSON attribute name.
    
    value - The value of the PASS attribute.
    
    limit - Maximum number of results.
    
    offset - Result offset.
    
    Returns:
    
    Set of all matching PASS entity URIs.
  - findAllByAttributes
```
<T extends PassEntity> Set<URI> findAllByAttributes(Class<T> modelClass,
                                                    Map<String,Object> attributeValuesMap)
```
    Retrieves URIs for MULTIPLE MATCHING RECORDS by matching the entity type and filtering by the attributes and values specified. An "AND" operator will be used for searching multiple attributes.
    For example, to find a Submission using a GrantId AND DOI:
```
   
   Map<String, Object> map = new HashMap<String, Object>();
   URI grantId = new URI("https://example.com/fedora/grants/3");
   String doi = "10.001/12345abc";
   map.put("grants", grantId)
   map.put("doi", doi);
   Set<URI> entityUris = findByAttribute(Submission.class, map);
 
```
    By default this will return a maximum of 200 matching records, unless the pass.elasticsearch.limit environment variable is set. If there are no matches, it will return an empty list.
    
    The Map "value" parameter will be converted to a String for the purpose of searching the index. The map's value cannot be a Collection. Where the attribute is a multi-valued field, only one value from that field should be provided. For example, if searching on Submission.repositories, a single repository URI should be provided for matching.
    Type Parameters:
    
    T - PASS entity type
    
    Parameters:
    
    modelClass - The class of PASS entity.
    
    attributeValuesMap - Map of JSON attributes to values.
    
    Returns:
    
    Set of all matching PASS entity URIs.
  - findAllByAttributes
```
<T extends PassEntity> Set<URI> findAllByAttributes(Class<T> modelClass,
                                                    Map<String,Object> attributeValuesMap,
                                                    int limit,
                                                    int offset)
```
    Retrieves URIs for MULTIPLE MATCHING RECORDS by matching the entity type and filtering by the attributes and values specified.
    For example, to find a Submission using a GrantId and DOI:
```
   
   Map<String, Object> map = new HashMap<String, Object>();
   URI grantId = new URI("https://example.com/fedora/grants/3");
   String doi = "10.001/12345abc";
   map.put("grants", grantId)
   map.put("doi", doi);
   Set<URI> entityUris = findByAttribute(Submission.class, map);
 
```
    The number of records will be limited by limit provided, and the offset will be applied to the default sorting. If there are no matches, it will return an empty list. This will override the limit env variable
    
    The Map "value" parameter will be converted to a String for the purpose of searching the index. The map's value cannot be a Collection. Where the attribute is a multi-valued field, only one value from that field should be provided. For example, if searching on Submission.repositories, a single repository URI should be provided for matching.
    Type Parameters:
    
    T - PASS entity type
    
    Parameters:
    
    modelClass - The class of PASS entity.
    
    attributeValuesMap - Map of JSON attribute name to values.
    
    limit - Maximum number of results.
    
    offset - Result offset.
    
    Returns:
    
    Set of all matching PASS entity URIs.
  - getIncoming
```
Map<String,Collection<URI>> getIncoming(URI passEntity)
```
    Retrieve inbound links to the repository resource identified by PassEntity.
    Keys in the returned map will be the predicate, and values will be the incoming URIs that reference the PassEntity.
    
    Parameters:
    
    passEntity - the URI of a repository resource
    
    Returns:
    
    a Map keyed by predicate, may be empty but never null
  - upload
```
URI upload(URI entityUri,
           InputStream content)
```
    POSTs the content to entityUri.
    The entityUri must already exist.
    
    Parameters:
    
    entityUri - a URI identifying an existing resource in the repository
    
    content - the content to POST to the resource
    
    Returns:
    
    the URI used to retrieve the uploaded content
  - upload
```
URI upload(URI entityUri,
           InputStream content,
           Map<String,?> params)
```
    POSTs the supplied content to the supplied entityUri. Optional parameters may be supplied by the caller, and used by the implementation to, e.g., supply checksums, suggest a "name" for the uploaded content.
    The entityUri must already exist.
    
    Supported parameters include:
    
    content-type
    
    the mime type of the content to be POSTed; added as a Content-Type header
    
    slug
    
    suggested name of the resource in the repository; added as a Slug header
    
    sha256
    
    hexadecimal encoded SHA-256 checksum of content; added as Digest header
    
    sha1
    
    hexadecimal encoded SHA-1 checksum of content; added as Digest header
    
    md5
    
    hexadecimal encoded MD5 checksum of content; added as Digest header
    
    filename
    
    name for content; added to a Content-Disposition header
    
    Parameters:
    
    entityUri - an existing entity in the repository
    
    content - the content to POST to the entity
    
    params - optional parameters to the POST, i.e. HTTP header values
    
    Returns:
    
    the URI used to retrieve the uploaded content
  - processAllEntities
```
<T extends PassEntity> int processAllEntities(Consumer<URI> processor,
                                              Class<T> modelClass)
```
    Visit all PASS entities in the repository of a given class.
    The search space for resources is set by the implementation. For example, all resources underneath a base URI in Fedora.
    
    Type Parameters:
    
    T - PASS entity type
    
    Parameters:
    
    processor - Consumer that is given a URI for every resource visited.
    
    modelClass - Class of PASS entity to visit. If null, will visit all classes.
    
    Returns:
    
    the number of entities visited.
  - processAllEntities
```
default <T extends PassEntity> int processAllEntities(Consumer<URI> processor)
```
    Visit all PASS entities
    The search space for resources is set by the implementation. For example, all resources underneath a base URI in Fedora.
    
    Type Parameters:
    
    T - PASS entity type
    
    Parameters:
    
    processor - Consumer that is given a URI for every resource visited.
    
    Returns:
    
    the number of entities visited

Interface PassClient

Method Summary

Method Detail

createResource

createAndReadResource

updateResource

updateAndReadResource

deleteResource

readResource

findByAttribute

findAllByAttribute

findAllByAttribute

findAllByAttributes

findAllByAttributes

getIncoming

upload

upload

processAllEntities

processAllEntities