http://git-wip-us.apache.org/repos/asf/atlas/blob/a1fd4068/omrs/src/main/java/org/apache/atlas/omrs/rest/repositoryconnector/OMRSRESTMetadataCollection.java ---------------------------------------------------------------------- diff --git a/omrs/src/main/java/org/apache/atlas/omrs/rest/repositoryconnector/OMRSRESTMetadataCollection.java b/omrs/src/main/java/org/apache/atlas/omrs/rest/repositoryconnector/OMRSRESTMetadataCollection.java index db48af7..3aa1330 100644 --- a/omrs/src/main/java/org/apache/atlas/omrs/rest/repositoryconnector/OMRSRESTMetadataCollection.java +++ b/omrs/src/main/java/org/apache/atlas/omrs/rest/repositoryconnector/OMRSRESTMetadataCollection.java @@ -17,8 +17,22 @@ */ package org.apache.atlas.omrs.rest.repositoryconnector; -import org.apache.atlas.omrs.ffdc.exception.NotImplementedRuntimeException; -import org.apache.atlas.omrs.metadatacollection.OMRSMetadataCollectionBase; +import org.apache.atlas.ocf.properties.Connection; +import org.apache.atlas.ocf.properties.Endpoint; +import org.apache.atlas.omrs.ffdc.OMRSErrorCode; +import org.apache.atlas.omrs.ffdc.exception.*; +import org.apache.atlas.omrs.localrepository.repositorycontentmanager.OMRSRepositoryHelper; +import org.apache.atlas.omrs.localrepository.repositorycontentmanager.OMRSRepositoryValidator; +import org.apache.atlas.omrs.metadatacollection.OMRSMetadataCollection; +import org.apache.atlas.omrs.metadatacollection.properties.MatchCriteria; +import org.apache.atlas.omrs.metadatacollection.properties.SequencingOrder; +import org.apache.atlas.omrs.metadatacollection.properties.instances.*; +import org.apache.atlas.omrs.metadatacollection.properties.typedefs.*; +import org.apache.atlas.omrs.rest.properties.*; +import org.springframework.web.client.RestTemplate; + +import java.util.Date; +import java.util.List; /** * The OMRSRESTMetadataCollection represents a remote metadata repository that supports the OMRS REST API. @@ -29,9 +43,16 @@ import org.apache.atlas.omrs.metadatacollection.OMRSMetadataCollectionBase; * This class is using OMRSMetadataCollectionBase while it is under construction. It will change to * inheriting from OMRSMetadataCollection once it is implemented */ -public class OMRSRESTMetadataCollection extends OMRSMetadataCollectionBase +public class OMRSRESTMetadataCollection extends OMRSMetadataCollection { - private OMRSRESTRepositoryConnector parentConnector = null; + static final private String defaultRepositoryName = "REST-connected Repository "; + + private OMRSRESTRepositoryConnector parentConnector; /* Initialized in constructor */ + private String metadataCollectionId; /* Initialized in constructor */ + private OMRSRepositoryHelper repositoryHelper; /* Initialized in constructor */ + private OMRSRepositoryValidator repositoryValidator; /* Initialized in constructor */ + private String repositoryName; /* Initialized in constructor */ + private String restURLRoot; /* Initialized in constructor */ /** * Default constructor. @@ -41,19 +62,4909 @@ public class OMRSRESTMetadataCollection extends OMRSMetadataCollectionBase * @param metadataCollectionId - unique identifier for the metadata collection */ public OMRSRESTMetadataCollection(OMRSRESTRepositoryConnector parentConnector, + OMRSRepositoryHelper repositoryHelper, + OMRSRepositoryValidator repositoryValidator, String metadataCollectionId) { + /* + * The metadata collection Id is the unique Id for the metadata collection. It is managed by the super class. + */ super(metadataCollectionId); + this.metadataCollectionId = metadataCollectionId; /* - * Save parentConnector since this has the connection information. + * Save parentConnector since this has the connection information and access to the metadata about the + * metadata cluster. */ this.parentConnector = parentConnector; /* - * This is a temporary implementation to allow the structural implementation of the connectors to - * be committed before the metadata collection implementation is complete. + * Save the repository helper and validator as they reduce the implementation effort of the metadata + * collection. */ - throw new NotImplementedRuntimeException("OMRSRESTMetadataCollection", "constructor", "ATLAS-1773"); + this.repositoryHelper = repositoryHelper; + this.repositoryValidator = repositoryValidator; + + /* + * The name of the repository comes from the connection + */ + Connection connection = parentConnector.getConnection(); + String endpointAddress = null; + + if (connection != null) + { + Endpoint endpoint = connection.getEndpoint(); + + if (endpoint != null) + { + endpointAddress = endpoint.getAddress(); + } + } + + this.repositoryName = defaultRepositoryName + endpointAddress; + this.restURLRoot = endpointAddress; + } + + + /* ====================================================================== + * Group 1: Confirm the identity of the metadata repository being called. + */ + + /** + * Returns the identifier of the metadata repository. This is the identifier used to register the + * metadata repository with the metadata repository cohort. It is also the identifier used to + * identify the home repository of a metadata instance. + * + * @return String - metadata collection id. + * @throws RepositoryErrorException - there is a problem communicating with the metadata repository. + */ + public String getMetadataCollectionId() throws RepositoryErrorException + { + final String methodName = "getMetadataCollectionId"; + final String urlTemplate = "metadata-collection-id"; + + String restResult = ""; + + try + { + RestTemplate restTemplate = new RestTemplate(); + + restResult = restTemplate.getForObject(restURLRoot + urlTemplate, restResult.getClass()); + } + catch (Throwable error) + { + OMRSErrorCode errorCode = OMRSErrorCode.REMOTE_REPOSITORY_ERROR; + String errorMessage = errorCode.getErrorMessageId() + + errorCode.getFormattedErrorMessage(methodName, + repositoryName, + error.getMessage()); + + throw new RepositoryErrorException(errorCode.getHTTPErrorCode(), + this.getClass().getName(), + methodName, + errorMessage, + errorCode.getSystemAction(), + errorCode.getUserAction(), + error); + } + + + if (restResult != null) + { + if (restResult.equals(super.metadataCollectionId)) + { + return restResult; + } + else + { + OMRSErrorCode errorCode = OMRSErrorCode.METADATA_COLLECTION_ID_MISMATCH; + String errorMessage = errorCode.getErrorMessageId() + + errorCode.getFormattedErrorMessage(repositoryName, + restResult, + super.metadataCollectionId); + + throw new RepositoryErrorException(errorCode.getHTTPErrorCode(), + this.getClass().getName(), + methodName, + errorMessage, + errorCode.getSystemAction(), + errorCode.getUserAction()); + } + } + else + { + OMRSErrorCode errorCode = OMRSErrorCode.NULL_METADATA_COLLECTION_ID; + String errorMessage = errorCode.getErrorMessageId() + + errorCode.getFormattedErrorMessage(repositoryName, super.metadataCollectionId); + + throw new RepositoryErrorException(errorCode.getHTTPErrorCode(), + this.getClass().getName(), + methodName, + errorMessage, + errorCode.getSystemAction(), + errorCode.getUserAction()); + } + } + + + /* ============================== + * Group 2: Working with typedefs + */ + + + /** + * Returns the list of different types of metadata organized into two groups. The first are the + * attribute type definitions (AttributeTypeDefs). These provide types for properties in full + * type definitions. Full type definitions (TypeDefs) describe types for entities, relationships + * and classifications. + * + * @param userId - unique identifier for requesting user. + * @return TypeDefGalleryResponse - List of different categories of type definitions. + * @throws RepositoryErrorException - there is a problem communicating with the metadata repository. + * @throws UserNotAuthorizedException - the userId is not permitted to perform this operation. + */ + public TypeDefGallery getAllTypes(String userId) throws RepositoryErrorException, + UserNotAuthorizedException + { + final String methodName = "getAllTypes"; + final String urlTemplate = "{0}/types/all"; + + TypeDefGalleryResponse restResult = this.callTypeDefGalleryGetRESTCall(methodName, + restURLRoot + urlTemplate, + userId); + + this.detectAndThrowUserNotAuthorizedException(methodName, restResult); + this.detectAndThrowRepositoryErrorException(methodName, restResult); + + return this.getTypeDefGalleryFromRESTResult(restResult); + } + + + /** + * Returns a list of type definitions that have the specified name. Type names should be unique. This + * method allows wildcard character to be included in the name. These are * (asterisk) for an + * arbitrary string of characters and ampersand for an arbitrary character. + * + * @param userId - unique identifier for requesting user. + * @param name - name of the TypeDefs to return (including wildcard characters). + * @return TypeDefGallery list. + * @throws InvalidParameterException - the name of the TypeDef is null. + * @throws RepositoryErrorException - there is a problem communicating with the metadata repository. + * @throws UserNotAuthorizedException - the userId is not permitted to perform this operation. + */ + public TypeDefGallery findTypesByName(String userId, + String name) throws InvalidParameterException, + RepositoryErrorException, + UserNotAuthorizedException + { + final String methodName = "findTypesByName"; + final String urlTemplate = "{0}/types/by-name?name={1}"; + + TypeDefGalleryResponse restResult = this.callTypeDefGalleryGetRESTCall(methodName, + restURLRoot + urlTemplate, + userId, + name); + + this.detectAndThrowInvalidParameterException(methodName, restResult); + this.detectAndThrowUserNotAuthorizedException(methodName, restResult); + this.detectAndThrowRepositoryErrorException(methodName, restResult); + + return this.getTypeDefGalleryFromRESTResult(restResult); + } + + + /** + * Returns all of the TypeDefs for a specific category. + * + * @param userId - unique identifier for requesting user. + * @param category - enum value for the category of TypeDef to return. + * @return TypeDefs list. + * @throws InvalidParameterException - the TypeDefCategory is null. + * @throws RepositoryErrorException - there is a problem communicating with the metadata repository. + * @throws UserNotAuthorizedException - the userId is not permitted to perform this operation. + */ + public List<TypeDef> findTypeDefsByCategory(String userId, + TypeDefCategory category) throws InvalidParameterException, + RepositoryErrorException, + UserNotAuthorizedException + { + final String methodName = "findTypeDefsByCategory"; + final String urlTemplate = "{0}/types/typedefs/by-category?category={1}"; + + TypeDefListResponse restResult = this.callTypeDefListGetRESTCall(methodName, + restURLRoot + urlTemplate, + userId, + category); + + this.detectAndThrowInvalidParameterException(methodName, restResult); + this.detectAndThrowUserNotAuthorizedException(methodName, restResult); + this.detectAndThrowRepositoryErrorException(methodName, restResult); + + return restResult.getTypeDefs(); + } + + + /** + * Returns all of the AttributeTypeDefs for a specific category. + * + * @param userId - unique identifier for requesting user. + * @param category - enum value for the category of an AttributeTypeDef to return. + * @return TypeDefs list. + * @throws InvalidParameterException - the TypeDefCategory is null. + * @throws RepositoryErrorException - there is a problem communicating with the metadata repository. + * @throws UserNotAuthorizedException - the userId is not permitted to perform this operation. + */ + public List<AttributeTypeDef> findAttributeTypeDefsByCategory(String userId, + AttributeTypeDefCategory category) throws InvalidParameterException, + RepositoryErrorException, + UserNotAuthorizedException + { + final String methodName = "findAttributeTypeDefsByCategory"; + final String urlTemplate = "{0}/types/attribute-typedefs/by-category?category={1}"; + + + AttributeTypeDefListResponse restResult = this.callAttributeTypeDefListGetRESTCall(methodName, + restURLRoot + urlTemplate, + userId, + category); + + this.detectAndThrowInvalidParameterException(methodName, restResult); + this.detectAndThrowUserNotAuthorizedException(methodName, restResult); + this.detectAndThrowRepositoryErrorException(methodName, restResult); + + return restResult.getAttributeTypeDefs(); + } + + + /** + * Return the TypeDefs that have the properties matching the supplied match criteria. + * + * @param userId - unique identifier for requesting user. + * @param matchCriteria - TypeDefProperties - a list of property names and values. + * @return TypeDefs list. + * @throws InvalidParameterException - the matchCriteria is null. + * @throws RepositoryErrorException - there is a problem communicating with the metadata repository. + * @throws UserNotAuthorizedException - the userId is not permitted to perform this operation. + */ + public List<TypeDef> findTypeDefsByProperty(String userId, + TypeDefProperties matchCriteria) throws InvalidParameterException, + RepositoryErrorException, + UserNotAuthorizedException + { + final String methodName = "findTypeDefsByProperty"; + final String urlTemplate = "{0}/types/typedefs/by-property?matchCriteria={1}"; + + TypeDefListResponse restResult = this.callTypeDefListGetRESTCall(methodName, + restURLRoot + urlTemplate, + userId, + matchCriteria); + + this.detectAndThrowInvalidParameterException(methodName, restResult); + this.detectAndThrowUserNotAuthorizedException(methodName, restResult); + this.detectAndThrowRepositoryErrorException(methodName, restResult); + + return restResult.getTypeDefs(); + } + + + /** + * Return the types that are linked to the elements from the specified standard. + * + * @param userId - unique identifier for requesting user. + * @param standard - name of the standard - null means any. + * @param organization - name of the organization - null means any. + * @param identifier - identifier of the element in the standard - null means any. + * @return TypeDefs list - each entry in the list contains a typedef. This is is a structure + * describing the TypeDef's category and properties. + * @throws InvalidParameterException - all attributes of the external id are null. + * @throws RepositoryErrorException - there is a problem communicating with the metadata repository. + * @throws UserNotAuthorizedException - the userId is not permitted to perform this operation. + */ + public List<TypeDef> findTypesByExternalID(String userId, + String standard, + String organization, + String identifier) throws InvalidParameterException, + RepositoryErrorException, + UserNotAuthorizedException + { + final String methodName = "findTypesByExternalID"; + final String urlTemplate = "{0}/types/typedefs/by-external-id?standard={1}&organization={2}&identifier={3}"; + + + TypeDefListResponse restResult = this.callTypeDefListGetRESTCall(methodName, + restURLRoot + urlTemplate, + userId, + standard, + organization, + identifier); + + this.detectAndThrowInvalidParameterException(methodName, restResult); + this.detectAndThrowUserNotAuthorizedException(methodName, restResult); + this.detectAndThrowRepositoryErrorException(methodName, restResult); + + return restResult.getTypeDefs(); + } + + + /** + * Return the TypeDefs that match the search criteria. + * + * @param userId - unique identifier for requesting user. + * @param searchCriteria - String - search criteria. + * @return TypeDefs list - each entry in the list contains a typedef. This is is a structure + * describing the TypeDef's category and properties. + * @throws InvalidParameterException - the searchCriteria is null. + * @throws RepositoryErrorException - there is a problem communicating with the metadata repository. + * @throws UserNotAuthorizedException - the userId is not permitted to perform this operation. + */ + public List<TypeDef> searchForTypeDefs(String userId, + String searchCriteria) throws InvalidParameterException, + RepositoryErrorException, + UserNotAuthorizedException + { + final String methodName = "searchForTypeDefs"; + final String urlTemplate = "{0}/types/typedefs/by-search-criteria?searchCriteria={1}"; + + TypeDefListResponse restResult = this.callTypeDefListGetRESTCall(methodName, + restURLRoot + urlTemplate, + userId, + searchCriteria); + + this.detectAndThrowInvalidParameterException(methodName, restResult); + this.detectAndThrowUserNotAuthorizedException(methodName, restResult); + this.detectAndThrowRepositoryErrorException(methodName, restResult); + + return restResult.getTypeDefs(); + } + + + /** + * Return the TypeDef identified by the GUID. + * + * @param userId - unique identifier for requesting user. + * @param guid - String unique id of the TypeDef. + * @return TypeDef structure describing its category and properties. + * @throws InvalidParameterException - the guid is null. + * @throws RepositoryErrorException - there is a problem communicating with the metadata repository where + * the metadata collection is stored. + * @throws TypeDefNotKnownException - The requested TypeDef is not known in the metadata collection. + * @throws UserNotAuthorizedException - the userId is not permitted to perform this operation. + */ + public TypeDef getTypeDefByGUID(String userId, + String guid) throws InvalidParameterException, + RepositoryErrorException, + TypeDefNotKnownException, + UserNotAuthorizedException + { + final String methodName = "getTypeDefByGUID"; + final String urlTemplate = "{0}/types/typedef/{1}"; + + TypeDefResponse restResult = this.callTypeDefGetRESTCall(methodName, + restURLRoot + urlTemplate, + userId, + guid); + + this.detectAndThrowInvalidParameterException(methodName, restResult); + this.detectAndThrowTypeDefNotKnownException(methodName, restResult); + this.detectAndThrowUserNotAuthorizedException(methodName, restResult); + this.detectAndThrowRepositoryErrorException(methodName, restResult); + + return restResult.getTypeDef(); + } + + + /** + * Return the AttributeTypeDef identified by the GUID. + * + * @param userId - unique identifier for requesting user. + * @param guid - String unique id of the TypeDef + * @return TypeDef structure describing its category and properties. + * @throws InvalidParameterException - the guid is null. + * @throws RepositoryErrorException - there is a problem communicating with the metadata repository where + * the metadata collection is stored. + * @throws TypeDefNotKnownException - The requested TypeDef is not known in the metadata collection. + * @throws UserNotAuthorizedException - the userId is not permitted to perform this operation. + */ + public AttributeTypeDef getAttributeTypeDefByGUID(String userId, + String guid) throws InvalidParameterException, + RepositoryErrorException, + TypeDefNotKnownException, + UserNotAuthorizedException + { + final String methodName = "getAttributeTypeDefByGUID"; + final String urlTemplate = "{0}/types/attribute-typedef/{1}"; + + AttributeTypeDefResponse restResult = this.callAttributeTypeDefGetRESTCall(methodName, + restURLRoot + urlTemplate, + userId, + guid); + + this.detectAndThrowInvalidParameterException(methodName, restResult); + this.detectAndThrowTypeDefNotKnownException(methodName, restResult); + this.detectAndThrowUserNotAuthorizedException(methodName, restResult); + this.detectAndThrowRepositoryErrorException(methodName, restResult); + + return restResult.getAttributeTypeDef(); + } + + + /** + * Return the TypeDef identified by the unique name. + * + * @param userId - unique identifier for requesting user. + * @param name - String name of the TypeDef. + * @return TypeDef structure describing its category and properties. + * @throws InvalidParameterException - the name is null. + * @throws RepositoryErrorException - there is a problem communicating with the metadata repository where + * the metadata collection is stored. + * @throws TypeDefNotKnownException - the requested TypeDef is not found in the metadata collection. + * @throws UserNotAuthorizedException - the userId is not permitted to perform this operation. + */ + public TypeDef getTypeDefByName(String userId, + String name) throws InvalidParameterException, + RepositoryErrorException, + TypeDefNotKnownException, + UserNotAuthorizedException + { + final String methodName = "getTypeDefByName"; + final String urlTemplate = "{0}/types/typedef/name/{1}"; + + TypeDefResponse restResult = this.callTypeDefGetRESTCall(methodName, + restURLRoot + urlTemplate, + userId, + name); + + this.detectAndThrowInvalidParameterException(methodName, restResult); + this.detectAndThrowTypeDefNotKnownException(methodName, restResult); + this.detectAndThrowUserNotAuthorizedException(methodName, restResult); + this.detectAndThrowRepositoryErrorException(methodName, restResult); + + return restResult.getTypeDef(); + } + + + /** + * Return the AttributeTypeDef identified by the unique name. + * + * @param userId - unique identifier for requesting user. + * @param name - String name of the TypeDef. + * @return TypeDef structure describing its category and properties. + * @throws InvalidParameterException - the name is null. + * @throws RepositoryErrorException - there is a problem communicating with the metadata repository where + * the metadata collection is stored. + * @throws TypeDefNotKnownException - the requested TypeDef is not found in the metadata collection. + * @throws UserNotAuthorizedException - the userId is not permitted to perform this operation. + */ + public AttributeTypeDef getAttributeTypeDefByName(String userId, + String name) throws InvalidParameterException, + RepositoryErrorException, + TypeDefNotKnownException, + UserNotAuthorizedException + { + final String methodName = "getAttributeTypeDefByName"; + final String urlTemplate = "{0}/types/attribute-typedef/name/{1}"; + + AttributeTypeDefResponse restResult = this.callAttributeTypeDefGetRESTCall(methodName, + restURLRoot + urlTemplate, + userId, + name); + + this.detectAndThrowInvalidParameterException(methodName, restResult); + this.detectAndThrowTypeDefNotKnownException(methodName, restResult); + this.detectAndThrowUserNotAuthorizedException(methodName, restResult); + this.detectAndThrowRepositoryErrorException(methodName, restResult); + + return restResult.getAttributeTypeDef(); + } + + + /** + * Create a collection of related types. + * + * @param userId - unique identifier for requesting user. + * @param newTypes - TypeDefGalleryResponse structure describing the new AttributeTypeDefs and TypeDefs. + * @throws InvalidParameterException - the new TypeDef is null. + * @throws RepositoryErrorException - there is a problem communicating with the metadata repository where + * the metadata collection is stored. + * @throws TypeDefNotSupportedException - the repository is not able to support this TypeDef. + * @throws TypeDefKnownException - the TypeDef is already stored in the repository. + * @throws TypeDefConflictException - the new TypeDef conflicts with an existing TypeDef. + * @throws InvalidTypeDefException - the new TypeDef has invalid contents. + * @throws FunctionNotSupportedException - the repository does not support this call. + * @throws UserNotAuthorizedException - the userId is not permitted to perform this operation. + */ + public void addTypeDefGallery(String userId, + TypeDefGallery newTypes) throws InvalidParameterException, + RepositoryErrorException, + TypeDefNotSupportedException, + TypeDefKnownException, + TypeDefConflictException, + InvalidTypeDefException, + FunctionNotSupportedException, + UserNotAuthorizedException + { + final String methodName = "addTypeDefGallery"; + final String urlTemplate = "{0}/types?newTypes={1}"; + + VoidResponse restResult = this.callVoidPostRESTCall(methodName, + restURLRoot + urlTemplate, + null, + userId, + newTypes); + + this.detectAndThrowInvalidParameterException(methodName, restResult); + this.detectAndThrowTypeDefNotSupportedException(methodName, restResult); + this.detectAndThrowFunctionNotSupportedException(methodName, restResult); + this.detectAndThrowTypeDefKnownException(methodName, restResult); + this.detectAndThrowTypeDefConflictException(methodName, restResult); + this.detectAndThrowInvalidTypeDefException(methodName, restResult); + this.detectAndThrowUserNotAuthorizedException(methodName, restResult); + this.detectAndThrowRepositoryErrorException(methodName, restResult); + } + + + /** + * Create a definition of a new TypeDef. + * + * @param userId - unique identifier for requesting user. + * @param newTypeDef - TypeDef structure describing the new TypeDef. + * @throws InvalidParameterException - the new TypeDef is null. + * @throws RepositoryErrorException - there is a problem communicating with the metadata repository where + * the metadata collection is stored. + * @throws TypeDefNotSupportedException - the repository is not able to support this TypeDef. + * @throws TypeDefKnownException - the TypeDef is already stored in the repository. + * @throws TypeDefConflictException - the new TypeDef conflicts with an existing TypeDef. + * @throws InvalidTypeDefException - the new TypeDef has invalid contents. + * @throws FunctionNotSupportedException - the repository does not support this call. + * @throws UserNotAuthorizedException - the userId is not permitted to perform this operation. + */ + public void addTypeDef(String userId, + TypeDef newTypeDef) throws InvalidParameterException, + RepositoryErrorException, + TypeDefNotSupportedException, + TypeDefKnownException, + TypeDefConflictException, + InvalidTypeDefException, + FunctionNotSupportedException, + UserNotAuthorizedException + { + final String methodName = "addTypeDef"; + final String urlTemplate = "{0}/types/typedef?newTypeDef={1}"; + + VoidResponse restResult = this.callVoidPostRESTCall(methodName, + restURLRoot + urlTemplate, + null, + userId, + newTypeDef); + + this.detectAndThrowInvalidParameterException(methodName, restResult); + this.detectAndThrowTypeDefNotSupportedException(methodName, restResult); + this.detectAndThrowTypeDefKnownException(methodName, restResult); + this.detectAndThrowTypeDefConflictException(methodName, restResult); + this.detectAndThrowInvalidTypeDefException(methodName, restResult); + this.detectAndThrowFunctionNotSupportedException(methodName, restResult); + this.detectAndThrowUserNotAuthorizedException(methodName, restResult); + this.detectAndThrowRepositoryErrorException(methodName, restResult); + } + + + /** + * Create a definition of a new AttributeTypeDef. + * + * @param userId - unique identifier for requesting user. + * @param newAttributeTypeDef - TypeDef structure describing the new TypeDef. + * @throws InvalidParameterException - the new TypeDef is null. + * @throws RepositoryErrorException - there is a problem communicating with the metadata repository where + * the metadata collection is stored. + * @throws TypeDefNotSupportedException - the repository is not able to support this TypeDef. + * @throws TypeDefKnownException - the TypeDef is already stored in the repository. + * @throws TypeDefConflictException - the new TypeDef conflicts with an existing TypeDef. + * @throws InvalidTypeDefException - the new TypeDef has invalid contents. + * @throws FunctionNotSupportedException - the repository does not support this call. + * @throws UserNotAuthorizedException - the userId is not permitted to perform this operation. + */ + public void addAttributeTypeDef(String userId, + AttributeTypeDef newAttributeTypeDef) throws InvalidParameterException, + RepositoryErrorException, + TypeDefNotSupportedException, + TypeDefKnownException, + TypeDefConflictException, + InvalidTypeDefException, + FunctionNotSupportedException, + UserNotAuthorizedException + { + final String methodName = "addAttributeTypeDef"; + final String urlTemplate = "{0}/types/attribute-typedef?newAttributeTypeDef={1}"; + + VoidResponse restResult = this.callVoidPostRESTCall(methodName, + restURLRoot + urlTemplate, + null, + userId, + newAttributeTypeDef); + + this.detectAndThrowInvalidParameterException(methodName, restResult); + this.detectAndThrowTypeDefNotSupportedException(methodName, restResult); + this.detectAndThrowTypeDefKnownException(methodName, restResult); + this.detectAndThrowTypeDefConflictException(methodName, restResult); + this.detectAndThrowInvalidTypeDefException(methodName, restResult); + this.detectAndThrowFunctionNotSupportedException(methodName, restResult); + this.detectAndThrowUserNotAuthorizedException(methodName, restResult); + this.detectAndThrowRepositoryErrorException(methodName, restResult); + } + + + /** + * Verify that a definition of a TypeDef is either new - or matches the definition already stored. + * + * @param userId - unique identifier for requesting user. + * @param typeDef - TypeDef structure describing the TypeDef to test. + * @return boolean - true means the TypeDef matches the local definition - false means the TypeDef is not known. + * @throws InvalidParameterException - the TypeDef is null. + * @throws RepositoryErrorException - there is a problem communicating with the metadata repository where + * the metadata collection is stored. + * @throws TypeDefNotSupportedException - the repository is not able to support this TypeDef. + * @throws TypeDefConflictException - the new TypeDef conflicts with an existing TypeDef. + * @throws InvalidTypeDefException - the new TypeDef has invalid contents. + * @throws UserNotAuthorizedException - the userId is not permitted to perform this operation. + */ + public boolean verifyTypeDef(String userId, + TypeDef typeDef) throws InvalidParameterException, + RepositoryErrorException, + TypeDefNotSupportedException, + TypeDefConflictException, + InvalidTypeDefException, + UserNotAuthorizedException + { + final String methodName = "verifyTypeDef"; + final String urlTemplate = "{0}/types/typedef/compatibility?typeDef={1}"; + + BooleanResponse restResult = this.callBooleanGetRESTCall(methodName, + restURLRoot + urlTemplate, + userId, + typeDef); + + this.detectAndThrowInvalidParameterException(methodName, restResult); + this.detectAndThrowTypeDefNotSupportedException(methodName, restResult); + this.detectAndThrowTypeDefConflictException(methodName, restResult); + this.detectAndThrowInvalidTypeDefException(methodName, restResult); + this.detectAndThrowUserNotAuthorizedException(methodName, restResult); + this.detectAndThrowRepositoryErrorException(methodName, restResult); + + return restResult.isFlag(); + } + + + /** + * Verify that a definition of an AttributeTypeDef is either new - or matches the definition already stored. + * + * @param userId - unique identifier for requesting user. + * @param attributeTypeDef - TypeDef structure describing the TypeDef to test. + * @return boolean - true means the TypeDef matches the local definition - false means the TypeDef is not known. + * @throws InvalidParameterException - the TypeDef is null. + * @throws RepositoryErrorException - there is a problem communicating with the metadata repository where + * the metadata collection is stored. + * @throws TypeDefNotSupportedException - the repository is not able to support this TypeDef. + * @throws TypeDefConflictException - the new TypeDef conflicts with an existing TypeDef. + * @throws InvalidTypeDefException - the new TypeDef has invalid contents. + * @throws UserNotAuthorizedException - the userId is not permitted to perform this operation. + */ + public boolean verifyAttributeTypeDef(String userId, + AttributeTypeDef attributeTypeDef) throws InvalidParameterException, + RepositoryErrorException, + TypeDefNotSupportedException, + TypeDefConflictException, + InvalidTypeDefException, + UserNotAuthorizedException + { + final String methodName = "verifyTypeDef"; + final String urlTemplate = "{0}/types/attribute-typedef/compatibility?attributeTypeDef={1}"; + + BooleanResponse restResult = this.callBooleanGetRESTCall(methodName, + restURLRoot + urlTemplate, + userId, + attributeTypeDef); + + this.detectAndThrowInvalidParameterException(methodName, restResult); + this.detectAndThrowTypeDefNotSupportedException(methodName, restResult); + this.detectAndThrowTypeDefConflictException(methodName, restResult); + this.detectAndThrowInvalidTypeDefException(methodName, restResult); + this.detectAndThrowUserNotAuthorizedException(methodName, restResult); + this.detectAndThrowRepositoryErrorException(methodName, restResult); + + return restResult.isFlag(); + } + + + /** + * Update one or more properties of the TypeDef. The TypeDefPatch controls what types of updates + * are safe to make to the TypeDef. + * + * @param userId - unique identifier for requesting user. + * @param typeDefPatch - TypeDef patch describing change to TypeDef. + * @return updated TypeDef + * @throws InvalidParameterException - the TypeDefPatch is null. + * @throws RepositoryErrorException - there is a problem communicating with the metadata repository where + * the metadata collection is stored. + * @throws TypeDefNotKnownException - the requested TypeDef is not found in the metadata collection. + * @throws PatchErrorException - the TypeDef can not be updated because the supplied patch is incompatible + * with the stored TypeDef. + * @throws FunctionNotSupportedException - the repository does not support this call. + * @throws UserNotAuthorizedException - the userId is not permitted to perform this operation. + */ + public TypeDef updateTypeDef(String userId, + TypeDefPatch typeDefPatch) throws InvalidParameterException, + RepositoryErrorException, + TypeDefNotKnownException, + PatchErrorException, + FunctionNotSupportedException, + UserNotAuthorizedException + { + final String methodName = "updateTypeDef"; + final String urlTemplate = "{0}/types/typedef?typeDefPatch={1}"; + + TypeDefResponse restResult = this.callTypeDefPatchRESTCall(methodName, + restURLRoot + urlTemplate, + null, + userId, + typeDefPatch); + + this.detectAndThrowInvalidParameterException(methodName, restResult); + this.detectAndThrowTypeDefNotKnownException(methodName, restResult); + this.detectAndThrowPatchErrorException(methodName, restResult); + this.detectAndThrowFunctionNotSupportedException(methodName, restResult); + this.detectAndThrowUserNotAuthorizedException(methodName, restResult); + this.detectAndThrowRepositoryErrorException(methodName, restResult); + + return restResult.getTypeDef(); + } + + + /** + * Delete the TypeDef. This is only possible if the TypeDef has never been used to create instances or any + * instances of this TypeDef have been purged from the metadata collection. + * + * @param userId - unique identifier for requesting user. + * @param obsoleteTypeDefGUID - String unique identifier for the TypeDef. + * @param obsoleteTypeDefName - String unique name for the TypeDef. + * @throws InvalidParameterException - the one of TypeDef identifiers is null. + * @throws RepositoryErrorException - there is a problem communicating with the metadata repository where + * the metadata collection is stored. + * @throws TypeDefNotKnownException - the requested TypeDef is not found in the metadata collection. + * @throws TypeDefInUseException - the TypeDef can not be deleted because there are instances of this type in the + * the metadata collection. These instances need to be purged before the + * TypeDef can be deleted. + * @throws FunctionNotSupportedException - the repository does not support this call. + * @throws UserNotAuthorizedException - the userId is not permitted to perform this operation. + */ + public void deleteTypeDef(String userId, + String obsoleteTypeDefGUID, + String obsoleteTypeDefName) throws InvalidParameterException, + RepositoryErrorException, + TypeDefNotKnownException, + TypeDefInUseException, + FunctionNotSupportedException, + UserNotAuthorizedException + { + final String methodName = "deleteTypeDef"; + final String urlTemplate = "{0}/types/typedef/{1}?obsoleteTypeDefName={2}"; + + VoidResponse restResult = this.callVoidPatchRESTCall(methodName, + restURLRoot + urlTemplate, + userId, + obsoleteTypeDefGUID, + obsoleteTypeDefName); + + this.detectAndThrowInvalidParameterException(methodName, restResult); + this.detectAndThrowTypeDefNotKnownException(methodName, restResult); + this.detectAndThrowTypeDefInUseException(methodName, restResult); + this.detectAndThrowFunctionNotSupportedException(methodName, restResult); + this.detectAndThrowUserNotAuthorizedException(methodName, restResult); + this.detectAndThrowRepositoryErrorException(methodName, restResult); + } + + + /** + * Delete an AttributeTypeDef. This is only possible if the AttributeTypeDef has never been used to create + * instances or any instances of this AttributeTypeDef have been purged from the metadata collection. + * + * @param userId - unique identifier for requesting user. + * @param obsoleteTypeDefGUID - String unique identifier for the AttributeTypeDef. + * @param obsoleteTypeDefName - String unique name for the AttributeTypeDef. + * @throws InvalidParameterException - the one of AttributeTypeDef identifiers is null. + * @throws RepositoryErrorException - there is a problem communicating with the metadata repository where + * the metadata collection is stored. + * @throws TypeDefNotKnownException - the requested AttributeTypeDef is not found in the metadata collection. + * @throws TypeDefInUseException - the AttributeTypeDef can not be deleted because there are instances of this type in the + * the metadata collection. These instances need to be purged before the + * AttributeTypeDef can be deleted. + * @throws FunctionNotSupportedException - the repository does not support this call. + * @throws UserNotAuthorizedException - the userId is not permitted to perform this operation. + */ + public void deleteAttributeTypeDef(String userId, + String obsoleteTypeDefGUID, + String obsoleteTypeDefName) throws InvalidParameterException, + RepositoryErrorException, + TypeDefNotKnownException, + TypeDefInUseException, + FunctionNotSupportedException, + UserNotAuthorizedException + { + final String methodName = "deleteAttributeTypeDef"; + final String urlTemplate = "{0}/types/attribute-typedef/{1}?obsoleteTypeDefName={2}"; + + VoidResponse restResult = this.callVoidPatchRESTCall(methodName, + restURLRoot + urlTemplate, + null, + userId, + obsoleteTypeDefGUID, + obsoleteTypeDefName); + + this.detectAndThrowInvalidParameterException(methodName, restResult); + this.detectAndThrowTypeDefNotKnownException(methodName, restResult); + this.detectAndThrowTypeDefInUseException(methodName, restResult); + this.detectAndThrowFunctionNotSupportedException(methodName, restResult); + this.detectAndThrowUserNotAuthorizedException(methodName, restResult); + this.detectAndThrowRepositoryErrorException(methodName, restResult); + } + + + /** + * Change the guid or name of an existing TypeDef to a new value. This is used if two different + * TypeDefs are discovered to have the same guid. This is extremely unlikely but not impossible so + * the open metadata protocol has provision for this. + * + * @param userId - unique identifier for requesting user. + * @param originalTypeDefGUID - the original guid of the TypeDef. + * @param originalTypeDefName - the original name of the TypeDef. + * @param newTypeDefGUID - the new identifier for the TypeDef. + * @param newTypeDefName - new name for this TypeDef. + * @return typeDef - new values for this TypeDef, including the new guid/name. + * @throws InvalidParameterException - one of the parameters is invalid or null. + * @throws RepositoryErrorException - there is a problem communicating with the metadata repository where + * the metadata collection is stored. + * @throws TypeDefNotKnownException - the TypeDef identified by the original guid/name is not found + * in the metadata collection. + * @throws FunctionNotSupportedException - the repository does not support this call. + * @throws UserNotAuthorizedException - the userId is not permitted to perform this operation. + */ + public TypeDef reIdentifyTypeDef(String userId, + String originalTypeDefGUID, + String originalTypeDefName, + String newTypeDefGUID, + String newTypeDefName) throws InvalidParameterException, + RepositoryErrorException, + TypeDefNotKnownException, + FunctionNotSupportedException, + UserNotAuthorizedException + { + final String methodName = "reIdentifyTypeDef"; + final String urlTemplate = "{0}/types/typedef/{1}/identifier?originalTypeDefName={2}&newTypeDefGUID={3}&newTypeDefName{4}"; + + TypeDefResponse restResult = this.callTypeDefPatchRESTCall(methodName, + restURLRoot + urlTemplate, + userId, + originalTypeDefGUID, + originalTypeDefName, + newTypeDefGUID, + newTypeDefName); + + this.detectAndThrowInvalidParameterException(methodName, restResult); + this.detectAndThrowTypeDefNotKnownException(methodName, restResult); + this.detectAndThrowFunctionNotSupportedException(methodName, restResult); + this.detectAndThrowUserNotAuthorizedException(methodName, restResult); + this.detectAndThrowRepositoryErrorException(methodName, restResult); + + return restResult.getTypeDef(); + } + + + /** + * Change the guid or name of an existing TypeDef to a new value. This is used if two different + * TypeDefs are discovered to have the same guid. This is extremely unlikely but not impossible so + * the open metadata protocol has provision for this. + * + * @param userId - unique identifier for requesting user. + * @param originalAttributeTypeDefGUID - the original guid of the AttributeTypeDef. + * @param originalAttributeTypeDefName - the original name of the AttributeTypeDef. + * @param newAttributeTypeDefGUID - the new identifier for the AttributeTypeDef. + * @param newAttributeTypeDefName - new name for this AttributeTypeDef. + * @return attributeTypeDef - new values for this AttributeTypeDef, including the new guid/name. + * @throws InvalidParameterException - one of the parameters is invalid or null. + * @throws RepositoryErrorException - there is a problem communicating with the metadata repository where + * the metadata collection is stored. + * @throws TypeDefNotKnownException - the AttributeTypeDef identified by the original guid/name is not + * found in the metadata collection. + * @throws FunctionNotSupportedException - the repository does not support this call. + * @throws UserNotAuthorizedException - the userId is not permitted to perform this operation. + */ + public AttributeTypeDef reIdentifyAttributeTypeDef(String userId, + String originalAttributeTypeDefGUID, + String originalAttributeTypeDefName, + String newAttributeTypeDefGUID, + String newAttributeTypeDefName) throws InvalidParameterException, + RepositoryErrorException, + TypeDefNotKnownException, + FunctionNotSupportedException, + UserNotAuthorizedException + { + final String methodName = "reIdentifyAttributeTypeDef"; + final String urlTemplate = "{0}/types/attribute-typedef/{1}/identifier?originalTypeDefName={2}&newTypeDefGUID={3}&newTypeDefName{4}"; + + AttributeTypeDefResponse restResult = this.callAttributeTypeDefPatchRESTCall(methodName, + restURLRoot + urlTemplate, + userId, + originalAttributeTypeDefGUID, + originalAttributeTypeDefName, + newAttributeTypeDefGUID, + newAttributeTypeDefName); + + this.detectAndThrowInvalidParameterException(methodName, restResult); + this.detectAndThrowFunctionNotSupportedException(methodName, restResult); + this.detectAndThrowTypeDefNotKnownException(methodName, restResult); + this.detectAndThrowUserNotAuthorizedException(methodName, restResult); + this.detectAndThrowRepositoryErrorException(methodName, restResult); + + return restResult.getAttributeTypeDef(); + } + + + /* =================================================== + * Group 3: Locating entity and relationship instances + */ + + + /** + * Returns a boolean indicating if the entity is stored in the metadata collection. + * + * @param userId - unique identifier for requesting user. + * @param guid - String unique identifier for the entity. + * @return entity details if the entity is found in the metadata collection; otherwise return null. + * @throws InvalidParameterException - the guid is null. + * @throws RepositoryErrorException - there is a problem communicating with the metadata repository where + * the metadata collection is stored. + * @throws UserNotAuthorizedException - the userId is not permitted to perform this operation. + */ + public EntityDetail isEntityKnown(String userId, + String guid) throws InvalidParameterException, + RepositoryErrorException, + UserNotAuthorizedException + { + final String methodName = "isEntityKnown"; + final String urlTemplate = "{0}/instances/entity/{1}/existence"; + + EntityDetailResponse restResult = this.callEntityDetailGetRESTCall(methodName, + restURLRoot + urlTemplate, + userId, + guid); + + this.detectAndThrowInvalidParameterException(methodName, restResult); + this.detectAndThrowUserNotAuthorizedException(methodName, restResult); + this.detectAndThrowRepositoryErrorException(methodName, restResult); + + return restResult.getEntity(); } + + + /** + * Return the header and classifications for a specific entity. + * + * @param userId - unique identifier for requesting user. + * @param guid - String unique identifier for the entity. + * @return EntitySummary structure + * @throws InvalidParameterException - the guid is null. + * @throws RepositoryErrorException - there is a problem communicating with the metadata repository where + * the metadata collection is stored. + * @throws EntityNotKnownException - the requested entity instance is not known in the metadata collection. + * @throws UserNotAuthorizedException - the userId is not permitted to perform this operation. + */ + public EntitySummary getEntitySummary(String userId, + String guid) throws InvalidParameterException, + RepositoryErrorException, + EntityNotKnownException, + UserNotAuthorizedException + { + final String methodName = "getEntitySummary"; + final String urlTemplate = "{0}/instances/entity/{1}/summary"; + + EntitySummaryResponse restResult = this.callEntitySummaryGetRESTCall(methodName, + restURLRoot + urlTemplate, + userId, + guid); + + this.detectAndThrowInvalidParameterException(methodName, restResult); + this.detectAndThrowEntityNotKnownException(methodName, restResult); + this.detectAndThrowUserNotAuthorizedException(methodName, restResult); + this.detectAndThrowRepositoryErrorException(methodName, restResult); + + return restResult.getEntity(); + } + + + /** + * Return the header, classifications and properties of a specific entity. + * + * @param userId - unique identifier for requesting user. + * @param guid - String unique identifier for the entity. + * @return EntityDetail structure. + * @throws InvalidParameterException - the guid is null. + * @throws RepositoryErrorException - there is a problem communicating with the metadata repository where + * the metadata collection is stored. + * @throws EntityNotKnownException - the requested entity instance is not known in the metadata collection. + * @throws EntityProxyOnlyException - the requested entity instance is only a proxy in the metadata collection. + * @throws UserNotAuthorizedException - the userId is not permitted to perform this operation. + */ + public EntityDetail getEntityDetail(String userId, + String guid) throws InvalidParameterException, + RepositoryErrorException, + EntityNotKnownException, + EntityProxyOnlyException, + UserNotAuthorizedException + { + final String methodName = "getEntityDetail"; + final String urlTemplate = "{0}/instances/entity/{1}"; + + EntityDetailResponse restResult = this.callEntityDetailGetRESTCall(methodName, + restURLRoot + urlTemplate, + userId, + guid); + + this.detectAndThrowInvalidParameterException(methodName, restResult); + this.detectAndThrowEntityNotKnownException(methodName, restResult); + this.detectAndThrowEntityProxyOnlyException(methodName, restResult); + this.detectAndThrowUserNotAuthorizedException(methodName, restResult); + this.detectAndThrowRepositoryErrorException(methodName, restResult); + + return restResult.getEntity(); + } + + + /** + * Return a historical versionName of an entity - includes the header, classifications and properties of the entity. + * + * @param userId - unique identifier for requesting user. + * @param guid - String unique identifier for the entity. + * @param asOfTime - the time used to determine which versionName of the entity that is desired. + * @return EntityDetail structure. + * @throws InvalidParameterException - the guid or date is null, or the asOfTime property is for a future time + * @throws RepositoryErrorException - there is a problem communicating with the metadata repository where + * the metadata collection is stored. + * @throws EntityNotKnownException - the requested entity instance is not known in the metadata collection + * at the time requested. + * @throws EntityProxyOnlyException - the requested entity instance is only a proxy in the metadata collection. + * @throws FunctionNotSupportedException - the repository does not support the asOfTime parameter. + * @throws UserNotAuthorizedException - the userId is not permitted to perform this operation. + */ + public EntityDetail getEntityDetail(String userId, + String guid, + Date asOfTime) throws InvalidParameterException, + RepositoryErrorException, + EntityNotKnownException, + EntityProxyOnlyException, + FunctionNotSupportedException, + UserNotAuthorizedException + { + final String methodName = "getEntityDetail"; + final String urlTemplate = "{0}/instances/entity/{1}/history"; + + EntityDetailResponse restResult = this.callEntityDetailGetRESTCall(methodName, + restURLRoot + urlTemplate, + userId, + guid); + + this.detectAndThrowInvalidParameterException(methodName, restResult); + this.detectAndThrowFunctionNotSupportedException(methodName,restResult); + this.detectAndThrowEntityNotKnownException(methodName, restResult); + this.detectAndThrowEntityProxyOnlyException(methodName, restResult); + this.detectAndThrowUserNotAuthorizedException(methodName, restResult); + this.detectAndThrowRepositoryErrorException(methodName, restResult); + + return restResult.getEntity(); + } + + + + /** + * Return the relationships for a specific entity. + * + * @param userId - unique identifier for requesting user. + * @param entityGUID - String unique identifier for the entity. + * @param relationshipTypeGUID - String GUID of the the type of relationship required (null for all). + * @param fromRelationshipElement - the starting element number of the relationships to return. + * This is used when retrieving elements + * beyond the first page of results. Zero means start from the first element. + * @param limitResultsByStatus - By default, relationships in all statuses are returned. However, it is possible + * to specify a list of statuses (eg ACTIVE) to restrict the results to. Null means all + * status values. + * @param asOfTime - Requests a historical query of the relationships for the entity. Null means return the + * present values. + * @param sequencingProperty - String name of the property that is to be used to sequence the results. + * Null means do not sequence on a property name (see SequencingOrder). + * @param sequencingOrder - Enum defining how the results should be ordered. + * @param pageSize -- the maximum number of result classifications that can be returned on this request. Zero means + * unrestricted return results size. + * @return Relationships list. Null means no relationships associated with the entity. + * @throws InvalidParameterException - a parameter is invalid or null. + * @throws RepositoryErrorException - there is a problem communicating with the metadata repository where + * the metadata collection is stored. + * @throws EntityNotKnownException - the requested entity instance is not known in the metadata collection. + * @throws PropertyErrorException - the sequencing property is not valid for the attached classifications. + * @throws PagingErrorException - the paging/sequencing parameters are set up incorrectly. + * @throws FunctionNotSupportedException - the repository does not support the asOfTime parameter. + * @throws UserNotAuthorizedException - the userId is not permitted to perform this operation. + */ + public List<Relationship> getRelationshipsForEntity(String userId, + String entityGUID, + String relationshipTypeGUID, + int fromRelationshipElement, + List<InstanceStatus> limitResultsByStatus, + Date asOfTime, + String sequencingProperty, + SequencingOrder sequencingOrder, + int pageSize) throws InvalidParameterException, + RepositoryErrorException, + EntityNotKnownException, + PropertyErrorException, + PagingErrorException, + FunctionNotSupportedException, + UserNotAuthorizedException + { + final String methodName = "getRelationshipsForEntity"; + final String urlTemplate = "{0}/instances/entity/{1}/relationships?relationshipTypeGUID={2}&fromRelationshipElement={3}&limitResultsByStatus={4}&asOfTime={5}&sequencingProperty={6}&sequencingOrder={7}&pageSize={8}"; + + RelationshipListResponse restResult = this.callRelationshipListGetRESTCall(methodName, + restURLRoot + urlTemplate, + userId, + entityGUID, + relationshipTypeGUID, + fromRelationshipElement, + limitResultsByStatus, + asOfTime, + sequencingProperty, + sequencingOrder, + pageSize); + + this.detectAndThrowInvalidParameterException(methodName, restResult); + this.detectAndThrowEntityNotKnownException(methodName, restResult); + this.detectAndThrowFunctionNotSupportedException(methodName, restResult); + this.detectAndThrowPropertyErrorException(methodName, restResult); + this.detectAndThrowPagingErrorException(methodName, restResult); + this.detectAndThrowUserNotAuthorizedException(methodName, restResult); + this.detectAndThrowRepositoryErrorException(methodName, restResult); + + return restResult.getRelationships(); + } + + + /** + * Return a list of entities that match the supplied properties according to the match criteria. The results + * can be returned over many pages. + * + * @param userId - unique identifier for requesting user. + * @param entityTypeGUID - String unique identifier for the entity type of interest (null means any entity type). + * @param matchProperties - List of entity properties to match to (null means match on entityTypeGUID only). + * @param matchCriteria - Enum defining how the properties should be matched to the entities in the repository. + * @param fromEntityElement - the starting element number of the entities to return. + * This is used when retrieving elements + * beyond the first page of results. Zero means start from the first element. + * @param limitResultsByStatus - By default, entities in all statuses are returned. However, it is possible + * to specify a list of statuses (eg ACTIVE) to restrict the results to. Null means all + * status values. + * @param limitResultsByClassification - List of classifications that must be present on all returned entities. + * @param asOfTime - Requests a historical query of the entity. Null means return the present values. + * @param sequencingProperty - String name of the entity property that is to be used to sequence the results. + * Null means do not sequence on a property name (see SequencingOrder). + * @param sequencingOrder - Enum defining how the results should be ordered. + * @param pageSize - the maximum number of result entities that can be returned on this request. Zero means + * unrestricted return results size. + * @return a list of entities matching the supplied criteria - null means no matching entities in the metadata + * collection. + * + * @throws InvalidParameterException - a parameter is invalid or null. + * @throws RepositoryErrorException - there is a problem communicating with the metadata repository where + * the metadata collection is stored. + * @throws TypeErrorException - the type guid passed on the request is not known by the + * metadata collection. + * @throws PropertyErrorException - the properties specified are not valid for any of the requested types of + * entity. + * @throws PagingErrorException - the paging/sequencing parameters are set up incorrectly. + * @throws FunctionNotSupportedException - the repository does not support the asOfTime parameter. + * @throws UserNotAuthorizedException - the userId is not permitted to perform this operation. + */ + public List<EntityDetail> findEntitiesByProperty(String userId, + String entityTypeGUID, + InstanceProperties matchProperties, + MatchCriteria matchCriteria, + int fromEntityElement, + List<InstanceStatus> limitResultsByStatus, + List<String> limitResultsByClassification, + Date asOfTime, + String sequencingProperty, + SequencingOrder sequencingOrder, + int pageSize) throws InvalidParameterException, + RepositoryErrorException, + TypeErrorException, + PropertyErrorException, + PagingErrorException, + FunctionNotSupportedException, + UserNotAuthorizedException + { + final String methodName = "findEntitiesByProperty"; + final String urlTemplate = "{0}/instances/entities/by-property?entityTypeGUID={1}&matchProperties={2}&matchCriteria={3}&fromEntityElement={4}&limitResultsByStatus={5}&limitResultsByClassification={6}&asOfTime={7}&sequencingProperty={8}&sequencingOrder={9}&pageSize={10}"; + + EntityListResponse restResult = this.callEntityListGetRESTCall(methodName, + restURLRoot + urlTemplate, + userId, + entityTypeGUID, + matchProperties, + matchCriteria, + fromEntityElement, + limitResultsByStatus, + limitResultsByClassification, + asOfTime, + sequencingProperty, + sequencingOrder, + pageSize); + + this.detectAndThrowFunctionNotSupportedException(methodName, restResult); + this.detectAndThrowInvalidParameterException(methodName, restResult); + this.detectAndThrowTypeErrorException(methodName, restResult); + this.detectAndThrowPropertyErrorException(methodName, restResult); + this.detectAndThrowPagingErrorException(methodName, restResult); + this.detectAndThrowUserNotAuthorizedException(methodName, restResult); + this.detectAndThrowRepositoryErrorException(methodName, restResult); + + return restResult.getEntities(); + } + + + /** + * Return a list of entities that have the requested type of classification attached. + * + * @param userId - unique identifier for requesting user. + * @param entityTypeGUID - unique identifier for the type of entity requested. Null mans any type of entity. + * @param classificationName - name of the classification - a null is not valid. + * @param matchClassificationProperties - list of classification properties used to narrow the search. + * @param matchCriteria - Enum defining how the properties should be matched to the classifications in the repository. + * @param fromEntityElement - the starting element number of the entities to return. + * This is used when retrieving elements + * beyond the first page of results. Zero means start from the first element. + * @param limitResultsByStatus - By default, entities in all statuses are returned. However, it is possible + * to specify a list of statuses (eg ACTIVE) to restrict the results to. Null means all + * status values. + * @param asOfTime - Requests a historical query of the entity. Null means return the present values. + * @param sequencingProperty - String name of the entity property that is to be used to sequence the results. + * Null means do not sequence on a property name (see SequencingOrder). + * @param sequencingOrder - Enum defining how the results should be ordered. + * @param pageSize - the maximum number of result entities that can be returned on this request. Zero means + * unrestricted return results size. + * @return a list of entities matching the supplied criteria - null means no matching entities in the metadata + * collection. + * @throws InvalidParameterException - a parameter is invalid or null. + * @throws RepositoryErrorException - there is a problem communicating with the metadata repository where + * the metadata collection is stored. + * @throws TypeErrorException - the type guid passed on the request is not known by the + * metadata collection. + * @throws ClassificationErrorException - the classification request is not known to the metadata collection. + * @throws PropertyErrorException - the properties specified are not valid for the requested type of + * classification. + * @throws PagingErrorException - the paging/sequencing parameters are set up incorrectly. + * @throws FunctionNotSupportedException - the repository does not support the asOfTime parameter. + * @throws UserNotAuthorizedException - the userId is not permitted to perform this operation. + */ + public List<EntityDetail> findEntitiesByClassification(String userId, + String entityTypeGUID, + String classificationName, + InstanceProperties matchClassificationProperties, + MatchCriteria matchCriteria, + int fromEntityElement, + List<InstanceStatus> limitResultsByStatus, + Date asOfTime, + String sequencingProperty, + SequencingOrder sequencingOrder, + int pageSize) throws InvalidParameterException, + RepositoryErrorException, + TypeErrorException, + ClassificationErrorException, + PropertyErrorException, + PagingErrorException, + FunctionNotSupportedException, + UserNotAuthorizedException + { + final String methodName = "findEntitiesByClassification"; + final String urlTemplate = "{0}/instances/entities/by-classification/{1}?entityTypeGUID={2}&matchClassificationProperties={3}&matchCriteria={4}&fromEntityElement={5}&limitResultsByStatus={6}&asOfTime={7}&sequencingProperty={8}&sequencingOrder={9}&pageSize={10}"; + + EntityListResponse restResult = this.callEntityListGetRESTCall(methodName, + restURLRoot + urlTemplate, + userId, + clas
<TRUNCATED>
