Package org.odpi.openmetadata.accessservices.digitalservice.client

Class CollectionsClient

java.lang.Object

org.odpi.openmetadata.accessservices.digitalservice.client.DigitalServiceBaseClient

org.odpi.openmetadata.accessservices.digitalservice.client.CollectionsClient

All Implemented Interfaces:

CollectionsInterface

public class CollectionsClient
extends DigitalServiceBaseClient
implements CollectionsInterface

The CollectionsClient supports requests related to collections.

Field Summary

Fields inherited from class org.odpi.openmetadata.accessservices.digitalservice.client.DigitalServiceBaseClient

invalidParameterHandler, openMetadataStoreClient, propertyHelper

Constructor Summary

Constructors

Constructor	Description
CollectionsClient(String serverName, String serverPlatformURLRoot, int maxPageSize)	Create a new client with no authentication embedded in the HTTP request.
CollectionsClient(String serverName, String serverPlatformURLRoot, String userId, String password, int maxPageSize)	Create a new client that passes userId and password in each HTTP request.

Method Summary

Modifier and Type	Method	Description
void	addToCollection(String userId, String collectionGUID, CollectionMembershipProperties membershipProperties, String elementGUID)	Add an element to a collection.
void	attachCollection(String userId, String collectionGUID, String parentGUID, ResourceListProperties collectionUse, boolean makeAnchor)	Connect an existing collection to an element using the ResourceList relationship (0019).
String	createCollection(String userId, String anchorGUID, boolean isOwnAnchor, String optionalClassification, CollectionProperties properties, String parentGUID, String parentRelationshipTypeName, ElementProperties parentRelationshipProperties, boolean parentAtEnd1)	Create a new generic collection.
String	createCollectionFromTemplate(String userId, String anchorGUID, boolean isOwnAnchor, Date effectiveFrom, Date effectiveTo, String templateGUID, ElementProperties replacementProperties, Map<String,String> placeholderProperties, String parentGUID, String parentRelationshipTypeName, ElementProperties parentRelationshipProperties, boolean parentAtEnd1)	Create a new metadata element to represent a collection using an existing metadata element as a template.
String	createDigitalProduct(String userId, String anchorGUID, boolean isOwnAnchor, CollectionProperties collectionProperties, DigitalProductProperties digitalProductProperties, String parentGUID, String parentRelationshipTypeName, ElementProperties parentRelationshipProperties, boolean parentAtEnd1)	Create a new collection that represents a digital product.
void	deleteCollection(String userId, String collectionGUID)	Delete a collection.
void	detachCollection(String userId, String collectionGUID, String parentGUID)	Detach an existing collection from an element.
List<CollectionElement>	findCollections(String userId, String searchString, int startFrom, int pageSize, Date effectiveTime)	Returns the list of collections matching the search string - this is coded as a regular expression.
List<CollectionElement>	getAttachedCollections(String userId, String parentGUID, String collectionType, int startFrom, int pageSize)	Returns the list of collections that are linked off of the supplied element.
List<CollectionElement>	getClassifiedCollections(String userId, String classificationName, int startFrom, int pageSize)	Returns the list of collections with a particular classification.
CollectionElement	getCollection(String userId, String collectionGUID)	Return the properties of a specific collection.
List<CollectionMember>	getCollectionMembers(String userId, String collectionGUID, int startFrom, int pageSize)	Return a list of elements that are a member of a collection.
List<CollectionElement>	getCollectionsByName(String userId, String name, int startFrom, int pageSize, Date effectiveTime)	Returns the list of collections with a particular name.
List<CollectionElement>	getCollectionsByType(String userId, String collectionType, int startFrom, int pageSize)	Returns the list of collections with a particular collectionType.
void	removeFromCollection(String userId, String collectionGUID, String elementGUID)	Remove an element from a collection.
void	updateCollection(String userId, String collectionGUID, boolean replaceAllProperties, CollectionProperties properties)	Update the properties of a collection.
void	updateCollectionMembership(String userId, String collectionGUID, boolean replaceAllProperties, CollectionMembershipProperties membershipProperties, String elementGUID)	Update an element's membership to a collection.
void	updateDigitalProduct(String userId, String collectionGUID, boolean replaceAllProperties, DigitalProductProperties properties)	Update the properties of the DigitalProduct classification attached to a collection.

Methods inherited from class java.lang.Object

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

Constructor Details

CollectionsClient

public CollectionsClient(String serverName,
 String serverPlatformURLRoot,
 int maxPageSize)
                  throws InvalidParameterException

Create a new client with no authentication embedded in the HTTP request.

Parameters:

serverName - name of the server to connect to

serverPlatformURLRoot - the network address of the server running the OMAS REST services

maxPageSize - number of elements that can be returned on a call

Throws:

InvalidParameterException - there is a problem creating the client-side components to issue any REST API calls.

CollectionsClient

public CollectionsClient(String serverName,
 String serverPlatformURLRoot,
 String userId,
 String password,
 int maxPageSize)
                  throws InvalidParameterException

Create a new client that passes userId and password in each HTTP request. This is the userId/password of the calling server. The end user's userId is sent on each request.

Parameters:

serverName - name of the server to connect to

serverPlatformURLRoot - the network address of the server running the OMAS REST services

userId - caller's userId embedded in all HTTP requests

password - caller's userId embedded in all HTTP requests

maxPageSize - number of elements that can be returned on a call

Throws:

InvalidParameterException - there is a problem creating the client-side components to issue any REST API calls.

Method Details

getAttachedCollections

public List<CollectionElement> getAttachedCollections(String userId,
 String parentGUID,
 String collectionType,
 int startFrom,
 int pageSize)
                                               throws InvalidParameterException,
PropertyServerException,
UserNotAuthorizedException

Returns the list of collections that are linked off of the supplied element.

Specified by:

getAttachedCollections in interface CollectionsInterface

Parameters:

userId - userId of user making request

parentGUID - unique identifier of referenceable object (typically a personal profile, project or community) that the collections hang off of

collectionType - filter response by collection type - if null, any value will do

startFrom - index of the list to start from (0 for start)

pageSize - maximum number of elements to return

Returns:

a list of collections

Throws:

InvalidParameterException - one of the parameters is null or invalid.

PropertyServerException - there is a problem retrieving information from the property server(s).

UserNotAuthorizedException - the requesting user is not authorized to issue this request.

getClassifiedCollections

public List<CollectionElement> getClassifiedCollections(String userId,
 String classificationName,
 int startFrom,
 int pageSize)
                                                 throws InvalidParameterException,
PropertyServerException,
UserNotAuthorizedException

Returns the list of collections with a particular classification.

Specified by:

getClassifiedCollections in interface CollectionsInterface

Parameters:

userId - userId of user making request

classificationName - name of the classification - if null, all collections are returned

startFrom - index of the list to start from (0 for start)

pageSize - maximum number of elements to return

Returns:

a list of collections

Throws:

InvalidParameterException - one of the parameters is null or invalid.

PropertyServerException - there is a problem retrieving information from the property server(s).

UserNotAuthorizedException - the requesting user is not authorized to issue this request.

findCollections

public List<CollectionElement> findCollections(String userId,
 String searchString,
 int startFrom,
 int pageSize,
 Date effectiveTime)
                                        throws InvalidParameterException,
PropertyServerException,
UserNotAuthorizedException

Returns the list of collections matching the search string - this is coded as a regular expression.

Specified by:

findCollections in interface CollectionsInterface

Parameters:

userId - userId of user making request

searchString - string to search for

startFrom - index of the list to start from (0 for start)

pageSize - maximum number of elements to return

effectiveTime - only return an element if it is effective at this time. Null means anytime. Use "new Date()" for now.

Returns:

a list of collections

Throws:

InvalidParameterException - one of the parameters is null or invalid.

PropertyServerException - there is a problem retrieving information from the property server(s).

UserNotAuthorizedException - the requesting user is not authorized to issue this request.

getCollectionsByName

public List<CollectionElement> getCollectionsByName(String userId,
 String name,
 int startFrom,
 int pageSize,
 Date effectiveTime)
                                             throws InvalidParameterException,
PropertyServerException,
UserNotAuthorizedException

Returns the list of collections with a particular name.

Specified by:

getCollectionsByName in interface CollectionsInterface

Parameters:

userId - userId of user making request

name - name of the collections to return - match is full text match in qualifiedName or name

startFrom - index of the list to start from (0 for start)

pageSize - maximum number of elements to return

effectiveTime - only return an element if it is effective at this time. Null means anytime. Use "new Date()" for now.

Returns:

a list of collections

Throws:

InvalidParameterException - one of the parameters is null or invalid.

PropertyServerException - there is a problem retrieving information from the property server(s).

UserNotAuthorizedException - the requesting user is not authorized to issue this request.

getCollectionsByType

public List<CollectionElement> getCollectionsByType(String userId,
 String collectionType,
 int startFrom,
 int pageSize)
                                             throws InvalidParameterException,
PropertyServerException,
UserNotAuthorizedException

Returns the list of collections with a particular collectionType. This is an optional text field in the collection element.

Specified by:

getCollectionsByType in interface CollectionsInterface

Parameters:

userId - userId of user making request

collectionType - the collection type value to match on. If it is null, all collections with a null collectionType are returned

startFrom - index of the list to start from (0 for start)

pageSize - maximum number of elements to return

Returns:

a list of collections

Throws:

InvalidParameterException - one of the parameters is null or invalid.

PropertyServerException - there is a problem retrieving information from the property server(s).

UserNotAuthorizedException - the requesting user is not authorized to issue this request.

getCollection

public CollectionElement getCollection(String userId,
 String collectionGUID)
                                throws InvalidParameterException,
PropertyServerException,
UserNotAuthorizedException

Return the properties of a specific collection.

Specified by:

getCollection in interface CollectionsInterface

Parameters:

userId - userId of user making request

collectionGUID - unique identifier of the required collection

Returns:

collection properties

Throws:

InvalidParameterException - one of the parameters is null or invalid.

PropertyServerException - there is a problem retrieving information from the property server(s).

UserNotAuthorizedException - the requesting user is not authorized to issue this request.

createCollection

public String createCollection(String userId,
 String anchorGUID,
 boolean isOwnAnchor,
 String optionalClassification,
 CollectionProperties properties,
 String parentGUID,
 String parentRelationshipTypeName,
 ElementProperties parentRelationshipProperties,
 boolean parentAtEnd1)
                        throws InvalidParameterException,
PropertyServerException,
UserNotAuthorizedException

Create a new generic collection.

Specified by:

createCollection in interface CollectionsInterface

Parameters:

userId - userId of user making request.

anchorGUID - unique identifier of the element that should be the anchor for the new element. Set to null if no anchor, or the Anchors classification is included in the initial classifications.

isOwnAnchor - boolean flag to day that the element should be classified as its own anchor once its element is created in the repository.

optionalClassification - classification of the collections - typically RootCollection, Set or Folder

properties - properties for the collection.

parentGUID - unique identifier of optional parent entity

parentRelationshipTypeName - type of relationship to connect the new element to the parent

parentRelationshipProperties - properties to include in parent relationship

parentAtEnd1 - which end should the parent GUID go in the relationship

Returns:

unique identifier of the newly created Collection

Throws:

InvalidParameterException - one of the parameters is invalid.

PropertyServerException - there is a problem retrieving information from the property server(s).

UserNotAuthorizedException - the requesting user is not authorized to issue this request.

createCollectionFromTemplate

public String createCollectionFromTemplate(String userId,
 String anchorGUID,
 boolean isOwnAnchor,
 Date effectiveFrom,
 Date effectiveTo,
 String templateGUID,
 ElementProperties replacementProperties,
 Map<String,String> placeholderProperties,
 String parentGUID,
 String parentRelationshipTypeName,
 ElementProperties parentRelationshipProperties,
 boolean parentAtEnd1)
                                    throws InvalidParameterException,
UserNotAuthorizedException,
PropertyServerException

Create a new metadata element to represent a collection using an existing metadata element as a template. The template defines additional classifications and relationships that should be added to the new collection.

Specified by:

createCollectionFromTemplate in interface CollectionsInterface

Parameters:

userId - calling user

anchorGUID - unique identifier of the element that should be the anchor for the new element. Set to null if no anchor, or the Anchors classification is included in the initial classifications.

isOwnAnchor - boolean flag to day that the element should be classified as its own anchor once its element is created in the repository.

effectiveFrom - the date when this element is active - null for active on creation

effectiveTo - the date when this element becomes inactive - null for active until deleted

templateGUID - the unique identifier of the existing asset to copy (this will copy all the attachments such as nested content, schema connection etc)

replacementProperties - properties of the new metadata element. These override the template values

placeholderProperties - property name-to-property value map to replace any placeholder values in the template element - and their anchored elements, which are also copied as part of this operation.

parentGUID - unique identifier of optional parent entity

parentRelationshipTypeName - type of relationship to connect the new element to the parent

parentRelationshipProperties - properties to include in parent relationship

parentAtEnd1 - which end should the parent GUID go in the relationship

Returns:

unique identifier of the new metadata element

Throws:

InvalidParameterException - one of the parameters is invalid

UserNotAuthorizedException - the user is not authorized to issue this request

PropertyServerException - there is a problem reported in the open metadata server(s)

createDigitalProduct

public String createDigitalProduct(String userId,
 String anchorGUID,
 boolean isOwnAnchor,
 CollectionProperties collectionProperties,
 DigitalProductProperties digitalProductProperties,
 String parentGUID,
 String parentRelationshipTypeName,
 ElementProperties parentRelationshipProperties,
 boolean parentAtEnd1)
                            throws InvalidParameterException,
PropertyServerException,
UserNotAuthorizedException

Create a new collection that represents a digital product.

Specified by:

createDigitalProduct in interface CollectionsInterface

Parameters:

userId - userId of user making request.

anchorGUID - unique identifier of the element that should be the anchor for the new element. Set to null if no anchor, or the Anchors classification is included in the initial classifications.

isOwnAnchor - boolean flag to day that the element should be classified as its own anchor once its element is created in the repository.

collectionProperties - properties for the collection.

digitalProductProperties - properties for the attached DigitalProduct classification

parentGUID - unique identifier of optional parent entity

parentRelationshipTypeName - type of relationship to connect the new element to the parent

parentRelationshipProperties - properties to include in parent relationship

parentAtEnd1 - which end should the parent GUID go in the relationship

Returns:

unique identifier of the newly created Collection

Throws:

InvalidParameterException - one of the parameters is invalid.

PropertyServerException - there is a problem retrieving information from the property server(s).

UserNotAuthorizedException - the requesting user is not authorized to issue this request.

updateCollection

public void updateCollection(String userId,
 String collectionGUID,
 boolean replaceAllProperties,
 CollectionProperties properties)
                      throws InvalidParameterException,
PropertyServerException,
UserNotAuthorizedException

Update the properties of a collection.

Specified by:

updateCollection in interface CollectionsInterface

Parameters:

userId - userId of user making request.

collectionGUID - unique identifier of the collection (returned from create)

replaceAllProperties - flag to indicate whether to completely replace the existing properties with the new properties, or just update the individual properties specified on the request.

properties - properties for the collection.

Throws:

InvalidParameterException - one of the parameters is invalid.

PropertyServerException - there is a problem retrieving information from the property server(s).

UserNotAuthorizedException - the requesting user is not authorized to issue this request.

updateDigitalProduct

public void updateDigitalProduct(String userId,
 String collectionGUID,
 boolean replaceAllProperties,
 DigitalProductProperties properties)
                          throws InvalidParameterException,
PropertyServerException,
UserNotAuthorizedException

Update the properties of the DigitalProduct classification attached to a collection.

Specified by:

updateDigitalProduct in interface CollectionsInterface

Parameters:

userId - userId of user making request.

collectionGUID - unique identifier of the collection (returned from create)

replaceAllProperties - flag to indicate whether to completely replace the existing properties with the new properties, or just update the individual properties specified on the request.

properties - properties for the DigitalProduct classification.

Throws:

InvalidParameterException - one of the parameters is invalid.

PropertyServerException - there is a problem retrieving information from the property server(s).

UserNotAuthorizedException - the requesting user is not authorized to issue this request.

attachCollection

public void attachCollection(String userId,
 String collectionGUID,
 String parentGUID,
 ResourceListProperties collectionUse,
 boolean makeAnchor)
                      throws InvalidParameterException,
PropertyServerException,
UserNotAuthorizedException

Connect an existing collection to an element using the ResourceList relationship (0019).

Specified by:

attachCollection in interface CollectionsInterface

Parameters:

userId - userId of user making request

collectionGUID - unique identifier of the collection

parentGUID - unique identifier of referenceable object that the collection should be attached to

collectionUse - description of how the collection will be used.

makeAnchor - like the lifecycle of the collection to that of the parent so that if the parent is deleted, so is the collection

Throws:

InvalidParameterException - one of the parameters is null or invalid.

PropertyServerException - there is a problem retrieving information from the property server(s).

UserNotAuthorizedException - the requesting user is not authorized to issue this request.

detachCollection

public void detachCollection(String userId,
 String collectionGUID,
 String parentGUID)
                      throws InvalidParameterException,
PropertyServerException,
UserNotAuthorizedException

Detach an existing collection from an element. If the collection is anchored to the element, it is deleted.

Specified by:

detachCollection in interface CollectionsInterface

Parameters:

userId - userId of user making request.

collectionGUID - unique identifier of the collection.

parentGUID - unique identifier of referenceable object that the collection should be attached to.

Throws:

InvalidParameterException - one of the parameters is null or invalid.

PropertyServerException - there is a problem retrieving information from the property server(s).

UserNotAuthorizedException - the requesting user is not authorized to issue this request.

deleteCollection

public void deleteCollection(String userId,
 String collectionGUID)
                      throws InvalidParameterException,
PropertyServerException,
UserNotAuthorizedException

Delete a collection. It is detected from all parent elements. If members are anchored to the collection then they are also deleted.

Specified by:

deleteCollection in interface CollectionsInterface

Parameters:

userId - userId of user making request.

collectionGUID - unique identifier of the collection.

Throws:

InvalidParameterException - one of the parameters is null or invalid.

PropertyServerException - there is a problem retrieving information from the property server(s).

UserNotAuthorizedException - the requesting user is not authorized to issue this request.

getCollectionMembers

public List<CollectionMember> getCollectionMembers(String userId,
 String collectionGUID,
 int startFrom,
 int pageSize)
                                            throws InvalidParameterException,
PropertyServerException,
UserNotAuthorizedException

Return a list of elements that are a member of a collection.

Specified by:

getCollectionMembers in interface CollectionsInterface

Parameters:

userId - userId of user making request.

collectionGUID - unique identifier of the collection.

startFrom - index of the list to start from (0 for start)

pageSize - maximum number of elements to return.

Returns:

list of asset details

Throws:

InvalidParameterException - one of the parameters is invalid.

PropertyServerException - there is a problem retrieving information from the property server(s).

UserNotAuthorizedException - the requesting user is not authorized to issue this request.

addToCollection

public void addToCollection(String userId,
 String collectionGUID,
 CollectionMembershipProperties membershipProperties,
 String elementGUID)
                     throws InvalidParameterException,
PropertyServerException,
UserNotAuthorizedException

Add an element to a collection.

Specified by:

addToCollection in interface CollectionsInterface

Parameters:

userId - userId of user making request.

collectionGUID - unique identifier of the collection.

membershipProperties - properties describing the membership characteristics.

elementGUID - unique identifier of the element.

Throws:

InvalidParameterException - one of the parameters is invalid.

PropertyServerException - there is a problem updating information in the property server(s).

UserNotAuthorizedException - the requesting user is not authorized to issue this request.

updateCollectionMembership

public void updateCollectionMembership(String userId,
 String collectionGUID,
 boolean replaceAllProperties,
 CollectionMembershipProperties membershipProperties,
 String elementGUID)
                                throws InvalidParameterException,
PropertyServerException,
UserNotAuthorizedException

Update an element's membership to a collection.

Specified by:

updateCollectionMembership in interface CollectionsInterface

Parameters:

userId - userId of user making request.

collectionGUID - unique identifier of the collection.

replaceAllProperties - flag to indicate whether to completely replace the existing properties with the new properties, or just update the individual properties specified on the request.

membershipProperties - properties describing the membership characteristics.

elementGUID - unique identifier of the element.

Throws:

InvalidParameterException - one of the parameters is invalid.

PropertyServerException - there is a problem updating information in the property server(s).

UserNotAuthorizedException - the requesting user is not authorized to issue this request.

removeFromCollection

public void removeFromCollection(String userId,
 String collectionGUID,
 String elementGUID)
                          throws InvalidParameterException,
PropertyServerException,
UserNotAuthorizedException

Remove an element from a collection.

Specified by:

removeFromCollection in interface CollectionsInterface

Parameters:

userId - userId of user making request.

collectionGUID - unique identifier of the collection.

elementGUID - unique identifier of the element.

Throws:

InvalidParameterException - one of the parameters is invalid.

PropertyServerException - there is a problem updating information in the property server(s).

UserNotAuthorizedException - the requesting user is not authorized to issue this request.