/*
 * NIST HL7 Web Service
 * RepositoryInterface.java Oct 23, 2007
 *
 * This code was produced by the National Institute of Standards and
 * Technology (NIST). See the "nist.disclaimer" file given in the distribution
 * for information on the use and redistribution of this software.
 */

package gov.nist.hl7.ws.repository;

/**
 *
 * This service provides a mechanism to store and retrieve artifacts related to the HL7
 * V2 standard such as message profiles.
 * <p>
 * @author Robert Snelick
 *
 */
public interface RepositoryInterface {

    /**
     * This method binds a profile and a resource together. It returns a new
     * handle OID that represents a "package" that consists of a profile and a resource.
     * @param profileOID an OID referencing a profile
     * @param resourceOID an OID referencing a resource
     * @return an OID referencing a handle to the artifacts that were successfully bound;
     * return null otherwise.
     */
    String bind(String profileOID, String resourceOID) throws Exception;

    /**
     * This method binds a profile and a resource together to a known handle OID.
     * @param profileOID an OID referencing a profile
     * @param resourceOID an OID referencing a resource
     * @param handleOID an OID referencing a package of a profile and resource(s)
     * @return true if the artifacts were successfully bound; false otherwise.
     */
    boolean bindWithOID(String profileOID, String resourceOID, String handleOID) throws Exception;

    /**
     * This method binds an additional resource to a known handle OID.
     * This method is used in cases where multiple resources are bound to a given profile.
     * @param resourceOID an OID referencing the resource to bind
     * @param handleOID an OID referencing a package of a profile and resource(s)
     * @return true if the resource was successfully bound; return false otherwise.
     */
    boolean bindAnotherResource(String resourceOID, String handleOID) throws Exception;

    /**
     * Use this method to retrieve a set of OIDs that are bound to a handle OID.
     * The method returns an array of strings. The first location in the String
     * array is the OID for the profile. Subsequent OIDs represents resources.
     * If the array is empty, the handle was not found.
     * @param handleOID an object identifier referencing a handle to a profile and possible resources
     * @return on success return an array of Strings in which the first location is the OID of the profile
     * and subsequent OIDs reference resources; if the handle OID was not found, the array is empty.
     */
    String[] getBindings(String handleOID) throws Exception;

    /**
     * Load a profile into the repository. The repository associates an OID with the profile. The OID is
     * returned on success.
     * <p>
     * @param xmlProfile an HL7 version message profile. The profile is an XML document
     * that follows the rules given in the HL7 version profile schema.
     * <p>
     * @return on success an OID; on failure the empty string
     */
    String loadProfile(String xmlProfile) throws Exception;

    /**
     * Load a profile (xmlProfile) into the repository and associated an object identifier (OID) with it.
     * <p>
     * @param xmlProfile an HL7 version message profile. The profile is an XML document
     * that follows the rules given in the HL7 version profile schema.
     * @param oid an object identifier referencing a profile
     * <p>
     * @return true if the profile was successfully loaded using the OID; false
     * otherwise.
     */
    boolean loadProfileWithOID(String xmlProfile, String oid) throws Exception;

    /**
     *
     * @param oid an object identifier referencing a profile
     * <p>
     * @return on success return an xmlProfile referenced by the OID; on failure return the empty string
     */
    String getProfile(String oid) throws Exception;

    /**
     * Load a resource into the repository. The repository associates an OID with the resource. The OID is
     * returned on success.
     * <p>
     * @param xmlResource a resource that is represented as XML file
     * <p>
     * @return on success an OID; on failure the empty string
     */
    String loadResource(String xmlResource) throws Exception;

    /**
     * Load a resource (xmlResource) into the repository and associated an object identifier (OID) with it.
     * <p>
     * @param xmlResource a resource that is represented as XML file
     * <p>
     * @param oid an object identifier referencing a resource
     * <p>
     * @return true if the resource was successfully loaded using the OID; false
     * otherwise.
     */
    boolean loadResourceWithOID(String xmlResource, String oid) throws Exception;

    /**
     *
     * @param oid an object identifier referencing a resource
     * <p>
     * @return on success return an xmlResource referenced by the OID; on failure return the empty string
     */
    String getResource(String oid) throws Exception;

    /**
     *
     * @param oid an object identifier referencing a profile
     * @return true if the profile reference by the OID is in the repository; false otherwise.
     */
    boolean queryRepository(String oid) throws Exception;

    /**
     *
     * @return an array of OIDs representing the profiles in the repository
     */
    String[] queryRepositoryForProfiles() throws Exception;

    /**
     *
     * @return an array of OIDs representing the resources in the repository
     */
    String[] queryRepositoryForResources() throws Exception;

    /**
     * Use this method to get a list of the handles in the repository.
     * A handle is an OID that links a profile (OID) and a set of resources
     * together as a single package (or handle).
     * @return an array of OIDs representing the handles in the repository
     * and for each handle return the bindings to that handle.
     */
    String[] queryRepositoryForHandles() throws Exception;

    /**
     * Get the message of the last exception caught.
     * <p>
     * @return a description of the last exception.
     */
    String getLastExceptionMessage() throws Exception;
}