You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@atlas.apache.org by da...@apache.org on 2018/02/16 09:52:24 UTC

[08/30] atlas git commit: ATLAS-2246: OMRS Connector API plus REST and IGC Connector skeleton - 15th February 2018

http://git-wip-us.apache.org/repos/asf/atlas/blob/8a57e657/omrs/src/main/java/org/apache/atlas/omrs/metadatacollection/OMRSMetadataCollection.java
----------------------------------------------------------------------
diff --git a/omrs/src/main/java/org/apache/atlas/omrs/metadatacollection/OMRSMetadataCollection.java b/omrs/src/main/java/org/apache/atlas/omrs/metadatacollection/OMRSMetadataCollection.java
new file mode 100644
index 0000000..5f0bd8b
--- /dev/null
+++ b/omrs/src/main/java/org/apache/atlas/omrs/metadatacollection/OMRSMetadataCollection.java
@@ -0,0 +1,1957 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ * <p/>
+ * http://www.apache.org/licenses/LICENSE-2.0
+ * <p/>
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.apache.atlas.omrs.metadatacollection;
+
+import org.apache.atlas.omrs.ffdc.*;
+import org.apache.atlas.omrs.ffdc.exception.*;
+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 java.util.ArrayList;
+import java.util.Date;
+
+/**
+ * <p>
+ *     OMRSMetadataCollection is the common interface for working with the contents of a metadata repository.
+ *     Within a metadata collection are the type definitions (TypeDefs) and metadata instances (Entities and
+ *     Relationships).
+ *
+ *     The methods on OMRSMetadataCollection are in the following major groups:
+ * </p>
+ * <ul>
+ *     <li><b>Methods to retrieve information about the metadata repository</b> -
+ *         Used to retrieve or confirm the identity of the metadata repository
+ *     </li>
+ *     <li><b>Methods for working with typedefs</b> -
+ *         Typedefs are used to define the type model for open metadata.
+ *         The open metadata support had a comprehensive set of typedefs implemented, and these can be augmented by
+ *         different vendors or applications.  The typedefs can be queried, created, updated and deleted though the
+ *         metadata collection.
+ *     </li>
+ *
+ *     <li><b>Methods for querying Entities and Relationships</b> -
+ *         The metadata repository stores instances of the typedefs as metadata instances.
+ *         Principally these are entities (nodes in the graph) and relationships (links between nodes).
+ *         Both the entities and relationships can have properties.
+ *         The entity may also have structured properties called structs and classifications attached.
+ *         This second group of methods supports a range of queries to retrieve these instances.
+ *     </li>
+ *
+ *     <li><b>Methods for maintaining the instances</b> -
+ *         The fourth group of methods supports the maintenance of the metadata instances.  Each instance as a status
+ *         (see InstanceStatus) that allows an instance to be proposed, drafted and approved before it becomes
+ *         active.  The instances can also be soft-deleted and restored or purged from the metadata
+ *         collection.
+ *     </li>
+ *     <li>
+ *         <b>Methods for repairing the metadata collections of the cohort</b> -
+ *         The fifth group of methods are for editing the control information of entities and relationships to
+ *         manage changes in the cohort.  These methods are advanced methods and are rarely used.
+ *     </li>
+ *     <li>
+ *         <b>Methods for local maintenance of a metadata collection</b>
+ *         The final group of methods are for removing reference copies of the metadata instances.  These updates
+ *         are not broadcast to the rest of the Cohort as events.
+ *     </li>
+ * </ul>
+ */
+public abstract class OMRSMetadataCollection
+{
+    protected  String     metadataCollectionId;
+
+    /**
+     * Constructor to save the metadata collection id.
+     *
+     * @param metadataCollectionId - unique identifier for the metadata collection
+     */
+    public OMRSMetadataCollection(String  metadataCollectionId)
+    {
+        this.metadataCollectionId = metadataCollectionId;
+
+        if (metadataCollectionId == null)
+        {
+            String            actionDescription = "OMRS Metadata Collection Constructor";
+
+            OMRSErrorCode errorCode = OMRSErrorCode.NULL_METADATA_COLLECTION_ID;
+            String        errorMessage = errorCode.getErrorMessageId()
+                                       + errorCode.getFormattedErrorMessage();
+
+            throw new OMRSLogicErrorException(errorCode.getHTTPErrorCode(),
+                                              this.getClass().getName(),
+                                              actionDescription,
+                                              errorMessage,
+                                              errorCode.getSystemAction(),
+                                              errorCode.getUserAction());
+
+        }
+    }
+
+
+    /* ======================================================================
+     * 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
+    {
+        return metadataCollectionId;
+    }
+
+
+    /* ==============================
+     * 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 TypeDefs - List of different categories of TypeDefs.
+     * @throws RepositoryErrorException - there is a problem communicating with the metadata repository.
+     * @throws UserNotAuthorizedException - the userId is not permitted to perform this operation.
+     */
+    public abstract TypeDefGallery getAllTypes(String  userId) throws RepositoryErrorException,
+                                                                      UserNotAuthorizedException;
+
+
+    /**
+     * 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 TypeDefs 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 abstract TypeDefGallery findTypesByName(String userId,
+                                                   String name) throws InvalidParameterException,
+                                                                       RepositoryErrorException,
+                                                                       UserNotAuthorizedException;
+
+
+    /**
+     * 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 abstract ArrayList<TypeDef> findTypeDefsByCategory(String          userId,
+                                                              TypeDefCategory category) throws InvalidParameterException,
+                                                                                               RepositoryErrorException,
+                                                                                               UserNotAuthorizedException;
+
+    /**
+     * 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 abstract ArrayList<AttributeTypeDef> findAttributeTypeDefsByCategory(String                   userId,
+                                                                                AttributeTypeDefCategory category) throws InvalidParameterException,
+                                                                                                                          RepositoryErrorException,
+                                                                                                                          UserNotAuthorizedException;
+
+    /**
+     * 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 abstract ArrayList<TypeDef> findTypeDefsByProperty(String            userId,
+                                                              TypeDefProperties matchCriteria) throws InvalidParameterException,
+                                                                                                      RepositoryErrorException,
+                                                                                                      UserNotAuthorizedException;
+
+
+    /**
+     * 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 abstract TypeDefGallery findTypesByExternalID(String    userId,
+                                                         String    standard,
+                                                         String    organization,
+                                                         String    identifier) throws InvalidParameterException,
+                                                                                      RepositoryErrorException,
+                                                                                      UserNotAuthorizedException;
+
+    /**
+     * 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 abstract ArrayList<TypeDef> searchForTypeDefs(String userId,
+                                                         String searchCriteria) throws InvalidParameterException,
+                                                                                       RepositoryErrorException,
+                                                                                       UserNotAuthorizedException;
+
+
+    /**
+     * 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 abstract TypeDef getTypeDefByGUID(String    userId,
+                                             String    guid) throws InvalidParameterException,
+                                                                    RepositoryErrorException,
+                                                                    TypeDefNotKnownException,
+                                                                    UserNotAuthorizedException;
+
+    /**
+     * 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 abstract AttributeTypeDef getAttributeTypeDefByGUID(String    userId,
+                                                               String    guid) throws InvalidParameterException,
+                                                                                      RepositoryErrorException,
+                                                                                      TypeDefNotKnownException,
+                                                                                      UserNotAuthorizedException;
+
+
+    /**
+     * 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 abstract TypeDef getTypeDefByName(String    userId,
+                                             String    name) throws InvalidParameterException,
+                                                                    RepositoryErrorException,
+                                                                    TypeDefNotKnownException,
+                                                                    UserNotAuthorizedException;
+
+
+    /**
+     * 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 abstract AttributeTypeDef getAttributeTypeDefByName(String    userId,
+                                                               String    name) throws InvalidParameterException,
+                                                                                      RepositoryErrorException,
+                                                                                      TypeDefNotKnownException,
+                                                                                      UserNotAuthorizedException;
+
+
+    /**
+     * Create a collection of related types.
+     *
+     * @param userId - unique identifier for requesting user.
+     * @param newTypes - TypeDefGallery 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 UserNotAuthorizedException - the userId is not permitted to perform this operation.
+     */
+    public abstract void addTypeDefGallery(String          userId,
+                                           TypeDefGallery  newTypes) throws InvalidParameterException,
+                                                                            RepositoryErrorException,
+                                                                            TypeDefNotSupportedException,
+                                                                            TypeDefKnownException,
+                                                                            TypeDefConflictException,
+                                                                            InvalidTypeDefException,
+                                                                            UserNotAuthorizedException;
+
+
+    /**
+     * 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 UserNotAuthorizedException - the userId is not permitted to perform this operation.
+     */
+    public abstract void addTypeDef(String       userId,
+                                    TypeDef      newTypeDef) throws InvalidParameterException,
+                                                                    RepositoryErrorException,
+                                                                    TypeDefNotSupportedException,
+                                                                    TypeDefKnownException,
+                                                                    TypeDefConflictException,
+                                                                    InvalidTypeDefException,
+                                                                    UserNotAuthorizedException;
+
+    /**
+     * 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 UserNotAuthorizedException - the userId is not permitted to perform this operation.
+     */
+    public abstract void addAttributeTypeDef(String             userId,
+                                             AttributeTypeDef   newAttributeTypeDef) throws InvalidParameterException,
+                                                                                            RepositoryErrorException,
+                                                                                            TypeDefNotSupportedException,
+                                                                                            TypeDefKnownException,
+                                                                                            TypeDefConflictException,
+                                                                                            InvalidTypeDefException,
+                                                                                            UserNotAuthorizedException;
+
+
+    /**
+     * 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 abstract boolean verifyTypeDef(String       userId,
+                                          TypeDef      typeDef) throws InvalidParameterException,
+                                                                       RepositoryErrorException,
+                                                                       TypeDefNotSupportedException,
+                                                                       TypeDefConflictException,
+                                                                       InvalidTypeDefException,
+                                                                       UserNotAuthorizedException;
+
+
+    /**
+     * 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 abstract boolean verifyAttributeTypeDef(String            userId,
+                                                   AttributeTypeDef  attributeTypeDef) throws InvalidParameterException,
+                                                                                              RepositoryErrorException,
+                                                                                              TypeDefNotSupportedException,
+                                                                                              TypeDefConflictException,
+                                                                                              InvalidTypeDefException,
+                                                                                              UserNotAuthorizedException;
+
+
+    /**
+     * 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 UserNotAuthorizedException - the userId is not permitted to perform this operation.
+     */
+    public abstract TypeDef updateTypeDef(String         userId,
+                                          TypeDefPatch   typeDefPatch) throws InvalidParameterException,
+                                                                              RepositoryErrorException,
+                                                                              TypeDefNotKnownException,
+                                                                              PatchErrorException,
+                                                                              UserNotAuthorizedException;
+
+
+    /**
+     * 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 UserNotAuthorizedException - the userId is not permitted to perform this operation.
+     */
+    public abstract void deleteTypeDef(String    userId,
+                                       String    obsoleteTypeDefGUID,
+                                       String    obsoleteTypeDefName) throws InvalidParameterException,
+                                                                             RepositoryErrorException,
+                                                                             TypeDefNotKnownException,
+                                                                             TypeDefInUseException,
+                                                                             UserNotAuthorizedException;
+
+
+    /**
+     * 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 UserNotAuthorizedException - the userId is not permitted to perform this operation.
+     */
+    public abstract void deleteAttributeTypeDef(String    userId,
+                                                String    obsoleteTypeDefGUID,
+                                                String    obsoleteTypeDefName) throws InvalidParameterException,
+                                                                                      RepositoryErrorException,
+                                                                                      TypeDefNotKnownException,
+                                                                                      TypeDefInUseException,
+                                                                                      UserNotAuthorizedException;
+
+
+    /**
+     * 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 UserNotAuthorizedException - the userId is not permitted to perform this operation.
+     */
+    public abstract TypeDef reIdentifyTypeDef(String     userId,
+                                              String     originalTypeDefGUID,
+                                              String     originalTypeDefName,
+                                              String     newTypeDefGUID,
+                                              String     newTypeDefName) throws InvalidParameterException,
+                                                                                RepositoryErrorException,
+                                                                                TypeDefNotKnownException,
+                                                                                UserNotAuthorizedException;
+
+
+    /**
+     * 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 UserNotAuthorizedException - the userId is not permitted to perform this operation.
+     */
+    public abstract AttributeTypeDef reIdentifyAttributeTypeDef(String     userId,
+                                                                String     originalAttributeTypeDefGUID,
+                                                                String     originalAttributeTypeDefName,
+                                                                String     newAttributeTypeDefGUID,
+                                                                String     newAttributeTypeDefName) throws InvalidParameterException,
+                                                                                                           RepositoryErrorException,
+                                                                                                           TypeDefNotKnownException,
+                                                                                                           UserNotAuthorizedException;
+
+
+    /* ===================================================
+     * 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 the 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 abstract EntityDetail  isEntityKnown(String     userId,
+                                                String     guid) throws InvalidParameterException,
+                                                                        RepositoryErrorException,
+                                                                        UserNotAuthorizedException;
+
+
+    /**
+     * 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 abstract EntitySummary getEntitySummary(String     userId,
+                                                   String     guid) throws InvalidParameterException,
+                                                                           RepositoryErrorException,
+                                                                           EntityNotKnownException,
+                                                                           UserNotAuthorizedException;
+
+
+
+    /**
+     * 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 UserNotAuthorizedException - the userId is not permitted to perform this operation.
+     */
+    public abstract EntityDetail getEntityDetail(String     userId,
+                                                 String     guid) throws InvalidParameterException,
+                                                                         RepositoryErrorException,
+                                                                         EntityNotKnownException,
+                                                                         UserNotAuthorizedException;
+
+
+    /**
+     * Return a historical version 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 version of the entity that is desired.
+     * @return EntityDetail structure.
+     * @throws InvalidParameterException - the guid or date 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
+     *                                   at the time requested.
+     * @throws PropertyErrorException - the asOfTime property is for a future time.
+     * @throws UserNotAuthorizedException - the userId is not permitted to perform this operation.
+     */
+    public abstract EntityDetail getEntityDetail(String     userId,
+                                                 String     guid,
+                                                 Date       asOfTime) throws InvalidParameterException,
+                                                                             RepositoryErrorException,
+                                                                             EntityNotKnownException,
+                                                                             PropertyErrorException,
+                                                                             UserNotAuthorizedException;
+
+
+    /**
+     * Return the header, classifications, properties and relationships for a specific entity.
+     *
+     * @param userId - unique identifier for requesting user.
+     * @param guid - String unique identifier for the entity.
+     * @return EntityUniverse 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 abstract EntityUniverse getEntityUniverse(String  userId,
+                                                     String  guid) throws InvalidParameterException,
+                                                                          RepositoryErrorException,
+                                                                          EntityNotKnownException,
+                                                                          UserNotAuthorizedException;
+
+
+
+    /**
+     * Return the relationships for a specific entity.
+     *
+     * @param userId - unique identifier for requesting user.
+     * @param entityGUID - String unique identifier for the entity.
+     * @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 UserNotAuthorizedException - the userId is not permitted to perform this operation.
+     */
+    public abstract ArrayList<Relationship> getRelationshipsForEntity(String                     userId,
+                                                                      String                     entityGUID,
+                                                                      int                        fromRelationshipElement,
+                                                                      ArrayList<InstanceStatus>  limitResultsByStatus,
+                                                                      Date                       asOfTime,
+                                                                      String                     sequencingProperty,
+                                                                      SequencingOrder            sequencingOrder,
+                                                                      int                        pageSize) throws InvalidParameterException,
+                                                                                                                  RepositoryErrorException,
+                                                                                                                  EntityNotKnownException,
+                                                                                                                  PropertyErrorException,
+                                                                                                                  PagingErrorException,
+                                                                                                                  UserNotAuthorizedException;
+
+
+
+    /**
+     * 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 fromEntityDetailElement - 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 UserNotAuthorizedException - the userId is not permitted to perform this operation.
+     */
+    public abstract ArrayList<EntityDetail> findEntitiesByProperty(String                    userId,
+                                                                   String                    entityTypeGUID,
+                                                                   InstanceProperties        matchProperties,
+                                                                   MatchCriteria             matchCriteria,
+                                                                   int                       fromEntityDetailElement,
+                                                                   ArrayList<InstanceStatus> limitResultsByStatus,
+                                                                   ArrayList<String>         limitResultsByClassification,
+                                                                   Date                      asOfTime,
+                                                                   String                    sequencingProperty,
+                                                                   SequencingOrder           sequencingOrder,
+                                                                   int                       pageSize) throws InvalidParameterException,
+                                                                                                              RepositoryErrorException,
+                                                                                                              TypeErrorException,
+                                                                                                              PropertyErrorException,
+                                                                                                              PagingErrorException,
+                                                                                                              UserNotAuthorizedException;
+
+
+    /**
+     * 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 fromEntityDetailElement - 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 UserNotAuthorizedException - the userId is not permitted to perform this operation.
+     */
+    public abstract ArrayList<EntityDetail> findEntitiesByClassification(String                    userId,
+                                                                         String                    entityTypeGUID,
+                                                                         String                    classificationName,
+                                                                         InstanceProperties        matchClassificationProperties,
+                                                                         MatchCriteria             matchCriteria,
+                                                                         ArrayList<InstanceStatus> limitResultsByStatus,
+                                                                         Date                      asOfTime,
+                                                                         String                    sequencingProperty,
+                                                                         SequencingOrder           sequencingOrder,
+                                                                         int                       fromEntityDetailElement,
+                                                                         int                       pageSize) throws InvalidParameterException,
+                                                                                                                    RepositoryErrorException,
+                                                                                                                    TypeErrorException,
+                                                                                                                    ClassificationErrorException,
+                                                                                                                    PropertyErrorException,
+                                                                                                                    PagingErrorException,
+                                                                                                                    UserNotAuthorizedException;
+
+
+    /**
+     * Return a list of entities matching the search criteria.
+     *
+     * @param userId - unique identifier for requesting user.
+     * @param searchCriteria - String expression of the characteristics of the required relationships.
+     * @param fromEntityDetailElement - 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 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 PropertyErrorException - the sequencing property specified is not valid for any of the requested types of
+     *                                  entity.
+     * @throws PagingErrorException - the paging/sequencing parameters are set up incorrectly.
+     * @throws UserNotAuthorizedException - the userId is not permitted to perform this operation.
+     */
+    public abstract ArrayList<EntityDetail> searchForEntities(String                          userId,
+                                                              String                          searchCriteria,
+                                                              int                             fromEntityDetailElement,
+                                                              ArrayList<InstanceStatus>       limitResultsByStatus,
+                                                              ArrayList<String>               limitResultsByClassification,
+                                                              Date                            asOfTime,
+                                                              String                          sequencingProperty,
+                                                              SequencingOrder                 sequencingOrder,
+                                                              int                             pageSize) throws InvalidParameterException,
+                                                                                                               RepositoryErrorException,
+                                                                                                               PropertyErrorException,
+                                                                                                               PagingErrorException,
+                                                                                                               UserNotAuthorizedException;
+
+
+    /**
+     * Returns a boolean indicating if the relationship is stored in the metadata collection.
+     *
+     * @param userId - unique identifier for requesting user.
+     * @param guid - String unique identifier for the relationship.
+     * @return relationship if the relationship 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 abstract Relationship  isRelationshipKnown(String     userId,
+                                                      String     guid) throws InvalidParameterException,
+                                                                              RepositoryErrorException,
+                                                                              UserNotAuthorizedException;
+
+
+    /**
+     * Return the current version of a requested relationship.
+     *
+     * @param userId - unique identifier for requesting user.
+     * @param guid - String unique identifier for the relationship.
+     * @return a relationship 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 RelationshipNotKnownException - the metadata collection does not have a relationship with
+     *                                         the requested GUID stored.
+     * @throws UserNotAuthorizedException - the userId is not permitted to perform this operation.
+     */
+    public abstract Relationship getRelationship(String    userId,
+                                                 String    guid) throws InvalidParameterException,
+                                                                        RepositoryErrorException,
+                                                                        RelationshipNotKnownException,
+                                                                        UserNotAuthorizedException;
+
+    /**
+     * Return a historical version of a relationship.
+     *
+     * @param userId - unique identifier for requesting user.
+     * @param guid - String unique identifier for the relationship.
+     * @param asOfTime - the time used to determine which version of the entity that is desired.
+     * @return EntityDetail structure.
+     * @throws InvalidParameterException - the guid or date is null.
+     * @throws RepositoryErrorException - there is a problem communicating with the metadata repository where
+     *                                 the metadata collection is stored.
+     * @throws RelationshipNotKnownException - the requested entity instance is not known in the metadata collection
+     *                                   at the time requested.
+     * @throws PropertyErrorException - the asOfTime property is for a future time.
+     * @throws UserNotAuthorizedException - the userId is not permitted to perform this operation.
+     */
+    public abstract Relationship getRelationship(String    userId,
+                                                 String    guid,
+                                                 Date      asOfTime) throws InvalidParameterException,
+                                                                            RepositoryErrorException,
+                                                                            RelationshipNotKnownException,
+                                                                            PropertyErrorException,
+                                                                            UserNotAuthorizedException;
+
+    /**
+     * Return a list of relationships that match the requested properties by hte matching criteria.   The results
+     * can be broken into pages.
+     *
+     * @param userId - unique identifier for requesting user.
+     * @param relationshipTypeGUID - unique identifier (guid) for the new relationship's type.
+     * @param matchProperties - list of  properties used to narrow the search.
+     * @param matchCriteria - Enum defining how the properties should be matched to the relationships in the repository.
+     * @param fromEntityDetailElement - 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, 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 relationships that can be returned on this request.  Zero means
+     *                 unrestricted return results size.
+     * @return a list of relationships.  Null means no matching relationships.
+     * @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 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
+     *                                  relationships.
+     * @throws PagingErrorException - the paging/sequencing parameters are set up incorrectly.
+     * @throws UserNotAuthorizedException - the userId is not permitted to perform this operation.
+     */
+    public abstract ArrayList<Relationship> findRelationshipsByProperty(String                    userId,
+                                                                        String                    relationshipTypeGUID,
+                                                                        InstanceProperties        matchProperties,
+                                                                        MatchCriteria             matchCriteria,
+                                                                        int                       fromEntityDetailElement,
+                                                                        ArrayList<InstanceStatus> limitResultsByStatus,
+                                                                        Date                      asOfTime,
+                                                                        String                    sequencingProperty,
+                                                                        SequencingOrder           sequencingOrder,
+                                                                        int                       pageSize) throws InvalidParameterException,
+                                                                                                                   RepositoryErrorException,
+                                                                                                                   TypeErrorException,
+                                                                                                                   PropertyErrorException,
+                                                                                                                   PagingErrorException,
+                                                                                                                   UserNotAuthorizedException;
+
+
+    /**
+     * Return a list of relationships that match the search criteria.  The results can be paged.
+     *
+     * @param userId - unique identifier for requesting user.
+     * @param searchCriteria - String expression of the characteristics of the required relationships.
+     * @param fromRelationshipElement - Element number of the results to skip to when building the results list
+     *                                to return.  Zero means begin at the start of the results.  This is used
+     *                                to retrieve the results over a number of pages.
+     * @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 relationships that can be returned on this request.  Zero means
+     *                 unrestricted return results size.
+     * @return a list of relationships.  Null means no matching relationships.
+     * @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 PropertyErrorException - there is a problem with one of the other parameters.
+     * @throws PagingErrorException - the paging/sequencing parameters are set up incorrectly.
+     * @throws UserNotAuthorizedException - the userId is not permitted to perform this operation.
+     */
+    public abstract ArrayList<Relationship> searchForRelationships(String                    userId,
+                                                                   String                    searchCriteria,
+                                                                   int                       fromRelationshipElement,
+                                                                   ArrayList<InstanceStatus> limitResultsByStatus,
+                                                                   Date                      asOfTime,
+                                                                   String                    sequencingProperty,
+                                                                   SequencingOrder           sequencingOrder,
+                                                                   int                       pageSize) throws InvalidParameterException,
+                                                                                                              RepositoryErrorException,
+                                                                                                              PropertyErrorException,
+                                                                                                              PagingErrorException,
+                                                                                                              UserNotAuthorizedException;
+
+
+    /**
+     * Return all of the relationships and intermediate entities that connect the startEntity with the endEntity.
+     *
+     * @param userId - unique identifier for requesting user.
+     * @param startEntityGUID - The entity that is used to anchor the query.
+     * @param endEntityGUID - the other entity that defines the scope of the query.
+     * @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.
+     * @return InstanceGraph - the sub-graph that represents the returned linked entities and their relationships.
+     * @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 EntityNotKnownException - the entity identified by either the startEntityGUID or the endEntityGUID
+     *                                   is not found in the metadata collection.
+     * @throws PropertyErrorException - there is a problem with one of the other parameters.
+     * @throws UserNotAuthorizedException - the userId is not permitted to perform this operation.
+     */
+    public abstract InstanceGraph getLinkingEntities(String                    userId,
+                                                     String                    startEntityGUID,
+                                                     String                    endEntityGUID,
+                                                     ArrayList<InstanceStatus> limitResultsByStatus,
+                                                     Date                      asOfTime) throws InvalidParameterException,
+                                                                                                RepositoryErrorException,
+                                                                                                EntityNotKnownException,
+                                                                                                PropertyErrorException,
+                                                                                                UserNotAuthorizedException;
+
+
+    /**
+     * Return the entities and relationships that radiate out from the supplied entity GUID.
+     * The results are scoped both the instance type guids and the level.
+     *
+     * @param userId - unique identifier for requesting user.
+     * @param entityGUID - the starting point of the query.
+     * @param entityTypeGUIDs - list of entity types to include in the query results.  Null means include
+     *                          all entities found, irrespective of their type.
+     * @param relationshipTypeGUIDs - list of relationship types to include in the query results.  Null means include
+     *                                all relationships found, irrespective of their type.
+     * @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 limitResultsByClassification - List of classifications that must be present on all returned entities.
+     * @param asOfTime - Requests a historical query of the relationships for the entity.  Null means return the
+     *                 present values.
+     * @param level - the number of the relationships out from the starting entity that the query will traverse to
+     *              gather results.
+     * @return InstanceGraph - the sub-graph that represents the returned linked entities and their relationships.
+     * @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 TypeErrorException - one or more of the type guids passed on the request is not known by the
+     *                              metadata collection.
+     * @throws EntityNotKnownException - the entity identified by the entityGUID is not found in the metadata collection.
+     * @throws PropertyErrorException - there is a problem with one of the other parameters.
+     * @throws UserNotAuthorizedException - the userId is not permitted to perform this operation.
+     */
+    public abstract InstanceGraph getEntityNeighborhood(String                    userId,
+                                                        String                    entityGUID,
+                                                        ArrayList<String>         entityTypeGUIDs,
+                                                        ArrayList<String>         relationshipTypeGUIDs,
+                                                        ArrayList<InstanceStatus> limitResultsByStatus,
+                                                        ArrayList<String>         limitResultsByClassification,
+                                                        Date                      asOfTime,
+                                                        int                       level) throws InvalidParameterException,
+                                                                                                RepositoryErrorException,
+                                                                                                TypeErrorException,
+                                                                                                EntityNotKnownException,
+                                                                                                PropertyErrorException,
+                                                                                                UserNotAuthorizedException;
+
+
+    /**
+     * Return the list of entities that are of the types listed in instanceTypes and are connected, either directly or
+     * indirectly to the entity identified by startEntityGUID.
+     *
+     * @param userId - unique identifier for requesting user.
+     * @param startEntityGUID - unique identifier of the starting entity.
+     * @param instanceTypes - list of types to search for.  Null means an type.
+     * @param fromEntityElement - starting element for results list.  Used in paging.  Zero means 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 limitResultsByClassification - List of classifications that must be present on all returned entities.
+     * @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 entities that can be returned on this request.  Zero means
+     *                 unrestricted return results size.
+     * @return list of entities either directly or indirectly connected to the start entity
+     * @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 TypeErrorException - the requested type is not known, or not supported in the metadata repository
+     *                              hosting the metadata collection.
+     * @throws EntityNotKnownException - the entity identified by the startEntityGUID
+     *                                   is not found in the metadata collection.
+     * @throws PropertyErrorException - the sequencing property specified is not valid for any of the requested types of
+     *                                  entity.
+     * @throws PagingErrorException - the paging/sequencing parameters are set up incorrectly.
+     * @throws UserNotAuthorizedException - the userId is not permitted to perform this operation.
+     */
+    public abstract ArrayList<EntityDetail> getRelatedEntities(String                    userId,
+                                                               String                    startEntityGUID,
+                                                               ArrayList<String>         instanceTypes,
+                                                               int                       fromEntityElement,
+                                                               ArrayList<InstanceStatus> limitResultsByStatus,
+                                                               ArrayList<String>         limitResultsByClassification,
+                                                               Date                      asOfTime,
+                                                               String                    sequencingProperty,
+                                                               SequencingOrder           sequencingOrder,
+                                                               int                       pageSize) throws InvalidParameterException,
+                                                                                                          RepositoryErrorException,
+                                                                                                          TypeErrorException,
+                                                                                                          EntityNotKnownException,
+                                                                                                          PropertyErrorException,
+                                                                                                          PagingErrorException,
+                                                                                                          UserNotAuthorizedException;
+
+
+    /* ======================================================
+     * Group 4: Maintaining entity and relationship instances
+     */
+
+    /**
+     * Create a new entity and put it in the requested state.  The new entity is returned.
+     *
+     * @param userId - unique identifier for requesting user.
+     * @param entityTypeGUID - unique identifier (guid) for the new entity's type.
+     * @param initialProperties - initial list of properties for the new entity - null means no properties.
+     * @param initialClassifications - initial list of classifications for the new entity - null means no classifications.
+     * @param initialStatus - initial status - typically DRAFT, PREPARED or ACTIVE.
+     * @return EntityDetail showing the new header plus the requested properties and classifications.  The entity will
+     * not have any relationships at this stage.
+     * @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 TypeErrorException - the requested type is not known, or not supported in the metadata repository
+     *                              hosting the metadata collection.
+     * @throws PropertyErrorException - one or more of the requested properties are not defined, or have different
+     *                                  characteristics in the TypeDef for this entity's type.
+     * @throws ClassificationErrorException - one or more of the requested classifications are either not known or
+     *                                           not defined for this entity type.
+     * @throws StatusNotSupportedException - the metadata repository hosting the metadata collection does not support
+     *                                       the requested status.
+     * @throws UserNotAuthorizedException - the userId is not permitted to perform this operation.
+     */
+    public abstract EntityDetail addEntity(String                     userId,
+                                           String                     entityTypeGUID,
+                                           InstanceProperties         initialProperties,
+                                           ArrayList<Classification>  initialClassifications,
+                                           InstanceStatus             initialStatus) throws InvalidParameterException,
+                                                                                            RepositoryErrorException,
+                                                                                            TypeErrorException,
+                                                                                            PropertyErrorException,
+                                                                                            ClassificationErrorException,
+                                                                                            StatusNotSupportedException,
+                                                                                            UserNotAuthorizedException;
+
+
+    /**
+     * Create an entity proxy in the metadata collection.  This is used to store relationships that span metadata
+     * repositories.
+     *
+     * @param userId - unique identifier for requesting user.
+     * @param entityProxy - details of entity to add.
+     * @throws InvalidParameterException - the entity proxy is null.
+     * @throws RepositoryErrorException - there is a problem communicating with the metadata repository where
+     *                                    the metadata collection is stored.
+     * @throws TypeErrorException - the requested type is not known, or not supported in the metadata repository
+     *                            hosting the metadata collection.
+     * @throws PropertyErrorException - one or more of the requested properties are not defined, or have different
+     *                                characteristics in the TypeDef for this entity's type.
+     * @throws ClassificationErrorException - one or more of the requested classifications are either not known or
+     *                                         not defined for this entity type.
+     * @throws StatusNotSupportedException - the metadata repository hosting the metadata collection does not support
+     *                                     the requested status.
+     * @throws UserNotAuthorizedException - the userId is not permitted to perform this operation.
+     */
+    public abstract void addEntityProxy(String       userId,
+                                        EntityProxy  entityProxy) throws InvalidParameterException,
+         

<TRUNCATED>