* * @author Chris Greenhalgh * @version 0.1 */ public interface IMIR3 { /*====================================================================== * Constants */ /** MIR3 localType values */ public static final String LOCAL_TYPE_DATA_THING = "DataThing"; public static final String LOCAL_TYPE_ASSOCIATION = "Association"; public static final String LOCAL_TYPE_STRING_ANNOTATION = "StringAnnotation"; public static final String LOCAL_TYPE_XML_ANNOTATION = "XMLAnnotation"; public static final String LOCAL_TYPE_USER = "User"; public static final String LOCAL_TYPE_WORK_CONTEXT = "WorkContext"; public static final String LOCAL_TYPE_CONCEPT = "Concept"; public static final String LOCAL_TYPE_PREDICATE = "Predicate"; public static final String LOCAL_TYPE_WF_INSTANCE = "WFInstance"; public static final String LOCAL_TYPE_WF_DEFINITION = "WFDefinition"; public static final String LOCAL_TYPE_PROXY_THING = "ProxyThing"; public static final String LOCAL_TYPE_COLLECTION = "Collection"; public static final String LOCAL_TYPE_COLLECTION_MEMBERS = "CollectionMembers"; // internal /** MIR3 standard metadata property names - Thing */ public static final String PROPERTY_LSID = "lsid"; public static final String PROPERTY_NAME = "name"; public static final String PROPERTY_LOCAL_TYPE = "localType"; public static final String PROPERTY_EXTERNAL_URI = "externalURI"; public static final String PROPERTY_CREATED = "created"; public static final String PROPERTY_CREATED_BY = "createdBy"; public static final String PROPERTY_DELETED = "deleted"; /** MIR3 standard metadata property names - User */ public static final String PROPERTY_X509_DN = "x509DN"; /** MIR3 standard metadata property names - Metadata */ public static final String PROPERTY_SUBJECT = "subject"; public static final String PROPERTY_PREDICATE = "predicate"; public static final String PROPERTY_PREDICATE_QUALIFIER = "predicateQualifier"; public static final String PROPERTY_AUTHORITATIVE = "authoritative"; public static final String PROPERTY_LITERAL_VALUE = "literalValue"; public static final String PROPERTY_OBJECT = "object"; public static final String PROPERTY_ASSOCIATION_DISTANCE = "associationDistance"; /** MIR3 standard metadata property names - DataThing */ public static final String PROPERTY_MIME_TYPE = "mimeType"; public static final String PROPERTY_XML_SCHEMA_URL = "xmlSchemaURL"; public static final String PROPERTY_XML_SCHEMA_NAME = "xmlSchemaName"; public static final String PROPERTY_LAST_MODIFIED = "lastModified"; public static final String PROPERTY_REVISION = "revision"; public static final String PROPERTY_CONCEPTS = "concepts"; public static final String PROPERTY_BINARY = "binary"; /** MIR3 standard metadata property names - Collection */ public static final String PROPERTY_MEMBERS_EXTERNAL_URI = "membersExternalURI"; /** MIR3 standard metadata property names - WFInstance */ public static final String PROPERTY_START_TIME = "startTime"; public static final String PROPERTY_STATUS = "status"; public static final String PROPERTY_DEFINED_BY = "definedBy"; public static final String PROPERTY_ENACTOR_ENDPOINT = "enactorEndpoint"; public static final String PROPERTY_ENACTOR_INSTANCE_ID = "enactorInstanceID"; /** MIR3 pseudo-standard metadata property names - datathings as input or output to/from wfinstance when using getWFInstanceAssociationsStandardMetadata */ public static final String PROPERTY_OUTPUT_QUALIFIER = "outputQualifier"; public static final String PROPERTY_INPUT_QUALIFIER = "inputQualifier"; /** MIR3 standard metadata property query values - Metadata */ /** authoritative */ public static final String PROPERTY_AUTHORITATIVE_Y = "y"; /** non-authoritative */ public static final String PROPERTY_AUTHORITATIVE_N = "n"; /** any non-null value for deleted, i.e. has been deleted */ public static final String PROPERTY_DELETED_NOT_NULL = "*"; /** null value for deleted, i.e. has not been deleted */ public static final String PROPERTY_DELETED_IS_NULL = "NULL"; /** MIR3 standard WFInstance association roles */ public static final String ASSOCIATION_ROLE_INPUT = "hasInput"; public static final String ASSOCIATION_ROLE_OUTPUT = "hasOutput"; /** MIR3 bootstrap Predicates */ public static final String PREDICATE_IS_A = "isA"; public static final String PREDICATE_IS_PART_OF = "isPartOf"; public static final String PREDICATE_WAS_CREATED_IN = "wasCreatedIn"; public static final String PREDICATE_HAS_INPUT = "hasInput"; public static final String PREDICATE_HAS_OUTPUT = "hasOutput"; public static final String PREDICATE_HAS_EQUIV_CLASS = "hasEquivClass"; public static final String PREDICATE_HAS_SUPER_CLASS = "hasSuperClass"; public static final String PREDICATE_HAS_SUPER_PREDICATE = "hasSuperPredicate"; public static final String PREDICATE_TOP_PREDICATE = "topPredicate"; public static final String PREDICATE_COMMENT = "comment"; /** MIR3 bootstrap Concepts (Classes) */ public static final String CONCEPT_TOP_CLASS = "TopClass"; public static final String CONCEPT_WF_PROVENANCE_RECORD = "WfProvenanceRecord"; public static final String CONCEPT_WF_DEFINITION_RECORD = "WfDefinition"; /** MIR3 standard MIME types */ public static final String MIME_TYPE_WF_DEFINITION = "text/x-mygrid-wf-definition"; public static final String MIME_TYPE_WF_INSTANCE = "text/x-mygrid-wf-instance"; public static final String MIME_TYPE_XML = "text/xml"; public static final String MIME_TYPE_TEXT_PLAIN = "text/plain"; public static final String MIME_TYPE_APPLICATION_BINARY = "application/binary"; /** MIR3 standard XML schemas - need to be defined! */ public static final String XML_SCHEMA_NAME_WF_DEFINITION = null; public static final String XML_SCHEMA_URL_WF_DEFINITION = null; public static final String XML_SCHEMA_NAME_WF_INSTANCE = null; public static final String XML_SCHEMA_URL_WF_INSTANCE = null; /** MIR3 bootstrap user id */ public static final String BOOTSTRAP_USER_URI = "user:init"; /*====================================================================== * initialise/bootstrap */ /** * check initial user, concepts, etc. are in MIR */ public void mir3CheckBootstrap() throws SQLException, InternalProblemException; /*====================================================================== * Thing / LSID */ /** * Retrieves _standard_ metadata of a Thing
* * @param externalURI The Thing * @return metaData The Thing's standard metadata, in a Hashtable, keyed by * 'lsid, 'name', 'localType', 'externalURI', 'created', 'createdBy' * @throws SQLException If an SQLException is propogated from the generic * query service * @throws InvalidRequestException throw if the LSID is unknown * @throws InternalProblemException */ public Hashtable getThingStandardMetadata(String externalURI) throws SQLException, InvalidRequestException, InternalProblemException; /** * Retrieves _standard_ metadata of anything using most-specific type
* * See getThingStandardMetadata, etc. * * @param anyExternalURI externalURI of whatever * @return metaData The most specific subclass's standard metadata, in a Hashtable * @throws SQLException If an SQLException is propogated from the generic * query service * @throws InvalidRequestException throw if the externalURI/LSID is unknown * @throws InternalProblemException */ public Hashtable getAnyStandardMetadata(String anyExternalURI) throws SQLException, InvalidRequestException, InternalProblemException; /** * Retrieves _standard_ metadata of list of anything using most-specific type
* * See getThingStandardMetadata, etc. * * @param anyExternalURIs array of externalURIs of whatever * @return metaData Array corresponding to input array with elements being * the most specific subclass's standard metadata, in a Hashtable * @throws SQLException If an SQLException is propogated from the generic * query service * @throws InvalidRequestException throw if the externalURI/LSID is unknown * @throws InternalProblemException */ public Hashtable[] getAnysStandardMetadata(String anyExternalURIs[]) throws SQLException, InvalidRequestException, InternalProblemException; /** * mark a Thing as deleted; may or may not affect garbage collection
* * more of an experimental placeholder, to give a way to avoid visual * clutter in interfaces. * * @param userID the userID for the requesting user * @param thingExternalURI the thing * @return int was already deleted -> 0; newly deleted -> 1 * @throws SQLException If an SQLException is propogated from the generic * query service * @throws InvalidRequestException throw if the externalURI/LSID is unknown * @throws UnknownUserException if the user is unknown */ public int markThingAsDeleted(String userID, String thingExternalURI) throws SQLException, UnknownUserException, InvalidRequestException; /*====================================================================== * User */ /** * Creates a new User object in the Users table * * @param createdByUserID userID (=externalURI) of creating User * @param userID the userID for the new user = externalURI for user * @param userName the normal full name of the user * @param userX509DN the user's X509 Distinguished Name (for certificates etc) * @return void * @throws SQLException If an SQLException is propogated up from the * generic query service * @throws InvalidRequestException If a user of this ID exists already. * @throws UnknownUserException if the creating user is unknown * @throws InternalProblemException * * Note: how does this relate to MIR security? */ public void addUser(String createdByUserID, String userID, String userName, String userX509DN) throws SQLException, InvalidRequestException, UnknownUserException, InternalProblemException; /** * Displays the users in the personal repository.
* * The UserID is displayed followed by the date of their creation * * Replaces PersRep2 getUserIDs (which returned Vector of name, modified) * * @return userIDs The UserIDs of the users (now just String [] names) * @throws SQLException If an SQLException is propogated up (re-thrown) * from the generic query service */ public String[] getUserIDsAsArray() throws SQLException; /** * Retrieves _standard_ metadata of a User
* * @param userID the user's ID (= externalURI) * @return metaData The user's standard metadata, in a Hashtable, * which includes that for a Thing (see getThingStandardMetadata) * plus 'x509DN' * @throws SQLException If an SQLException is propogated from the generic * query service * @throws UnknownUserException throw if the userID is unknown * @throws InternalProblemException */ public Hashtable getUserStandardMetadata(String userID) throws SQLException, UnknownUserException, InternalProblemException; /*====================================================================== * Association */ /** * Add an association between subject and object
* * @param createdByUserID userID of creating User * @param subjectExternalURI ExternalURI of Thing, subject of association * @param addUnknownSubjectAs (if non-null) if subjectExternalURI * is unknown then add as this localType. * Reasonable options: 'Concept', 'Predicate', * 'ProxyThing', 'WorkContext' only. * @param predicateExternalURI externalURI of predicate for association * @param predicateQualifier optional qualifier of predicate * @param addUnknownPredicate add predicate if unknown * @param objectExternalURI externalURI of object for association * @param addUnkownObjectAs (if non-null) if objectExternalURI * is unknown then add as this localType. * Reasonable options: 'Concept', 'Predicate', * 'ProxyThing', 'WorkContext' only. * @param distance distance of association if inferred (1 for direct) * @param authoritative the association should be regarded as such * @return associationExternalURI * @throws SQLException If an SQLException is propogated from the generic * query service * @throws UnknownUserException if the creating user is unknown * @throws UnknownPredicateException if predicate unknown and not to be added * @throws InvalidRequestException if object unknown and not to be added * @throws InternalProblemException */ public String addAssociation(String createdByUserID, String subjectExternalURI, String addUnknownSubjectAs, String predicateExternalURI, String predicateQualifier, boolean addUnknownPredicate, String objectExternalURI, String addUnknownObjectAs, int distance, boolean authoritative) throws SQLException, UnknownUserException, UnknownPredicateException, InvalidRequestException, InternalProblemException; /** * Add StringAnnotation
* * @param createdByUserID userID of creating User * @param subjectExternalURI ExternalURI of Thing, subject of association * @param addUnkownSubjectAs (if non-null) if subjectExternalURI * is unknown then add as this localType. * Reasonable options: 'Concept', 'Predicate', * 'ProxyThing', 'WorkContext' only. * @param predicateExternalURI externalURI of predicate for association * @param predicateQualifier optional qualifier of predicate * @param addUnknownPredicateFlag add predicate if unknown * @param literalValue literal value * @param authoritative the association should be regarded as such * @return StringAnnotationExternalURI * @throws SQLException If an SQLException is propogated from the generic * query service * @throws UnknownUserException if the creating user is unknown * @throws UnknownPredicateException if predicate unknown and not to be added * @throws InvalidRequestException if object unknown and not to be added * @throws InternalProblemException */ public String addStringAnnotation(String createdByUserID, String subjectExternalURI, String addUnknownSubjectAs, String predicateExternalURI, String predicateQualifier, boolean addUnknownPredicate, String literalValue, boolean authoritative) throws SQLException, UnknownUserException, UnknownPredicateException, InternalProblemException, InvalidRequestException; /** * get ExternalURIs of Metadata by matching a subset of its properties
* * Note: does not currently take account of metadata referencing a Collection's * membersExternalURI of which a subject or object isPartOf. * * @param localType i.e. 'Association', 'StringAnnotation', * or 'XMLAnnotation' (optional, null is wildcard) * @param subjectExternalURI subject ExternalURI (optional, null is wildcard) * @param predicateURI predicate external URI (optional, null is wildcard) * @param predicateQualifier predicate qualifier (optional, null is wildcard) * @param literalValue literalValue (StringAnnotation only) (optional, null is wildcard) * @param objectExternalURI ExternalURI of object (for associations) (optional, null is wildcard) * @param properties Optional Hashtable of optional properties to match, currently * 'authoritative'->'y' or 'n', 'deleted'->'*' or 'null', * 'associationDistance'->int (as string) (taken as max value). Ignored * if null. * @return ExternalURIs of annotations - String [] * @throws SQLException If an SQLException is propogated from the generic * query service * @throws UnknownPredicateException If the predicate is unknown * * MIR3Note: no subsumption over predicates there yet */ public String[] getMetadataExternalURIsBySimpleMatch (String localType, String subjectExternalURI, String predicateURI, String predicateQualifier, String literalValue, String objectExternalURI, Hashtable properties) throws SQLException, UnknownPredicateException, InternalProblemException, InvalidRequestException; /** * get associated ExternalURIs by simple match
* * Note: does not currently take account of metadata referencing a Collection's * membersExternalURI of which a subject or object isPartOf. * * @param subjectExternalURI subject ExternalURI (optional, null is wildcard) * @param predicateURI predicate external URI (optional, null is wildcard) * @param predicateQualifier optional predicate qualifier (optional, null is wildcard) * @param literalValue literalValue (StringAnnotation only) (optional, null is wildcard) * @param objectExternalURI ExternalURI of object (for associations) (optional, null is wildcard) * @param properties Optional Hashtable of optional properties to match, currently * 'authoritative'->'y' or 'n', 'deleted'->'*' or 'null', * 'associationDistance'->int (as string) (taken as max value). Ignored * if null. * @return associatedURIs subject externalURIs if subjectExternalURI * is null, else object externalURIs * @throws SQLException If an SQLException is propogated from the generic * query service * @throws UnknownPredicateException If the predicate is unknown */ public String[] getAssociatedExternalURIsBySimpleMatch (String localType, String subjectExternalURI, String predicateURI, String predicateQualifier, String literalValue, String objectExternalURI, Hashtable properties) throws SQLException, UnknownPredicateException, InternalProblemException, InvalidRequestException; /** * Retrieves _standard_ metadata of a MetaData thing
* * MetaData includes: StringAnnotation, XMLAnnotation, and Association. * * Standard MetaData (in addition to Thing - see GetThingStandardMetadata): * * Any/all: 'subject' (ExternalURI), 'predicate' (URI), * 'predicateQualifier' (may be null), * 'authoritative' (present if authoritative, value "1") * * StringAnnotation: 'literalValue' (String) * * Association: 'object' (ExternalURI), 'associationDistance' (String of int) * * XMLAnnotation: add DataThing standard Metadata. * * @param metadataExternalURI the metadata item's ExternalURI * @return metaData The MetaData's standard metadata, in a Hashtable * @throws SQLException If an SQLException is propogated from the generic * query service * @throws InvalidRequestException throw if the userID is unknown * @throws InternalProblemException */ public Hashtable getMetadataStandardMetadata(String metadataExternalURI) throws SQLException, InvalidRequestException, InternalProblemException; /*====================================================================== * Concept and Predicate */ /** * Stores a new Concept in the MIR
* * Replaces PersRep2 storeConceptType * * @param createdByUserID userID of creating User * @param conceptExternalURI The URI of the concept type * @return Status 1 if concept was novel; 0 if already present * @throws SQLException If an SQLException is propogated from the generic * query service * @throws UnknownUserException if the creating user is unknown * @throws UnknownPredicateException internal error (from add assoc.) * @throws UnknownConceptException internal error (from add assoc.) */ public int addConcept(String createdByUserName, String conceptExternalURI) throws SQLException, UnknownUserException, UnknownPredicateException, UnknownConceptException, InternalProblemException, InvalidRequestException; /** * Stores a new Predicate in the MIR
* * @param createdByUserID userID of creating User * @param predicateExernalURI The URI of the predicate type * @return Status 1 if predicate was novel; 0 if already present * @throws SQLException If an SQLException is propogated from the generic * query service * @throws UnknownUserException if the creating user is unknown * @throws UnknownConceptException internal error (from add assoc.) * @throws UnknownPredicateException internal error (from add assoc.) */ public int addPredicate(String createdByUserName, String predicateExternalURI) throws SQLException, UnknownUserException, UnknownPredicateException, UnknownConceptException, InternalProblemException, InvalidRequestException; /*====================================================================== * DataThing - was DomainEntity */ /** * Creates a new DataThing in the MIR.
* * Replaces PersRep2 createDomainEntity * * Note: values are normally String (including XML documents) or byte[] * (binary, which may be internalised in the database in some encoding * such as base64, although this should not be externally visible). * * @param createdByUserID userID of creating User * @param workContextExternalURI 'home' work context for DataThing * @param mimeType MIME type of (unwrapped) value, e.g. text/xml, text/plain, image/gif * @param xmlSchemaURL The url to the XML schema (optional, default to null) * @param xmlSchemaName The name of the XML schema (optional, default to null) * @param value The value, either as String or byte[]. As a special case, * a value of null will allow you exactly one use of * setDataThingValue to assign the actual value, and * potentially change mimeType, schema, add concepts. * Please don't provide a null unless you have no alternative * because it muddies the waters of provenance. * @param name The name of the domain entity given by the user (optional, default null) * @param externalURI An external URI for the 'original' version of this * (optional - null to ignore; defaults to autogenerated LSID; do not * use unless you know why) * @param conceptURIs The concept URIs describing the domain entity * @param addUnknownConcepts Add unknown conceptURIs * @return ExternalURI The ExternalURI URI of the newly created object * @throws SQLException If an SQLException is propogated from the generic * query service * @throws UnknownUserException if the creating user is unknown * @throws UnknownPredicateException internal error (from add assoc.) * @throws UnknownConceptException internal error (from add assoc.) * @throws InvalidRequestException e.g. ill-formed XML * @throws DuplicateIDException externalURI already exists in MIR * @throws InternalProblemException */ public String addDataThing(String createdByUserID, String workContextExternalURI, String mimeType, String xmlSchemaURL, String xmlSchemaName, Object value, String name, String externalURI, String [] conceptURIs, boolean addUnknownConcepts) throws SQLException, UnknownUserException, UnknownPredicateException, UnknownConceptException, InvalidRequestException, DuplicateIDException, InternalProblemException; /** * Assign a value to a DataThing created without one.
* * See addDataThing. * * @param createdByUserID userID of creating User * @param externalURI The external URI of the previously added DataThing. * @param mimeType MIME type of (unwrapped) value, e.g. text/xml, text/plain, image/gif * @param xmlSchemaURL The url to the XML schema (optional, default to null) * @param xmlSchemaName The name of the XML schema (optional, default to null) * @param value The value, either as String or byte[]. * @param conceptURIs The concept URIs describing the domain entity; * will be ADDED to any given to addDataThing. * null is ignored. * @param addUnknownConcepts Add unknown conceptURIs * @return void * @throws SQLException If an SQLException is propogated from the generic * query service * @throws UnknownUserException if the creating user is unknown * @throws UnknownPredicateException internal error (from add assoc.) * @throws UnknownConceptException internal error (from add assoc.) * @throws InvalidRequestException e.g. ill-formed XML, or value already set * @throws DuplicateIDException externalURI already exists in MIR * @throws InternalProblemException */ public void setDataThingValue(String createdByUserID, String externalURI, String mimeType, String xmlSchemaURL, String xmlSchemaName, Object value, String [] conceptURIs, boolean addUnknownConcepts) throws SQLException, UnknownUserException, UnknownPredicateException, UnknownConceptException, InvalidRequestException, DuplicateIDException, InternalProblemException; /** * Stores an output DomainEntity produced from the execution of a workflow
* * See addDataThing - only additional parameters described here. * * Note: workContext is inferred from the wfInstance's workContext. * * @param wfInstanceExternalURI ExternalURI from addWFInstance * which generated the domain entities * @param outputQualifier the name of the output (e.g. message) * part/arg; becomes Metadata predicateQualifier * @return ExternalURI The ExternalURI URI of the newly created object * (optional, leave unused null; defaults to autogen. LSID) * @throws SQLException If an SQLException is propogated from the generic * query service * @throws UnknownUserException if the creating user is unknown * @throws UnknownPredicateException internal error (from add assoc.) * @throws UnknownConceptException internal error (from add assoc.) * @throws InvalidRequestException e.g. ill-formed XML * @throws DuplicateIDException externalURI already exists in MIR * @throws InternalProblemException */ public String addOutputDataThing(String createdByUserID, String mimeType, String xmlSchemaURL, String xmlSchemaName, Object value, String name, String externalURI, String [] conceptURIs, boolean addUnknownConcepts, String wfInstanceExternalURI, String outputQualifier) throws SQLException, UnknownUserException, UnknownPredicateException, UnknownConceptException, InvalidRequestException, DuplicateIDException, InternalProblemException; /** * Creates a new XMLAnnotation in the MIR.
* * Note: values are normally String (including XML documents) or byte[] * (binary, which may be internalised in the database in some encoding * such as base64, although this should not be externally visible). * * @param createdByUserID userID of creating User * @param subjectExternalURI ExternalURI of Thing, subject of association (must be in MIR) * @param addUnknownSubjectAs (if non-null) if subjectExternalURI * is unknown then add as this localType. * Reasonable options: 'Concept', 'Predicate', * 'ProxyThing', 'WorkContext' only. * @param predicateExternalURI externalURI of predicate for association * @param predicateQualifier optional qualifier of predicate * @param addUnknownPredicateFlag add predicate if unknown * @param authoritative the association should be regarded as such * @param mimeType MIME type of (unwrapped) value, e.g. text/xml, text/plain, image/gif * @param xmlSchemaURL The url to the XML schema (optional, default to null) * @param xmlSchemaName The name of the XML schema (optional, default to null) * @param value The value, either as String or byte[]. * @param name The name of the domain entity given by the user (optional, default to null) * @param externalURI An external URI for the 'original' version of this (optional, default to null) * @param conceptURIs The concept URIs describing the domain entity * @param addUnknownConcepts Add unknown conceptURIs * @return ExternalURI The ExternalURI URI of the newly created object * @throws SQLException If an SQLException is propogated from the generic * query service * @throws UnknownUserException if the creating user is unknown * @throws UnknownPredicateException internal error (from add assoc.) * @throws UnknownConceptException internal error (from add assoc.) * @throws InvalidRequestException e.g. ill-formed XML * @throws InternalProblemException * @throws DuplicateIDException externalURI already exists in MIR */ public String addXMLAnnotation(String createdByUserID, String subjectExternalURI, String addUnknownSubjectAs, String predicateExternalURI, String predicateQualifier, boolean addUnknownPredicate, boolean authoritative, String mimeType, String xmlSchemaURL, String xmlSchemaName, Object value, String name, String externalURI, String [] conceptURIs, boolean addUnknownConcepts) throws SQLException, UnknownUserException, UnknownPredicateException, UnknownConceptException, InvalidRequestException, DuplicateIDException, InternalProblemException; /** * Retrieves _standard_ metadata of a DataThing
* * metadata returned in a hashtable, standard properties (keys) in addition to Thing: * 'mimeType', 'xmlSchemaURL', 'xmlSchemaName', 'lastModified', 'revision' and * 'concepts' (String[] or Vector of String), 'binary' * * @param externalURI the DataThing's externalURI * @return metaData The data thing's standard metadata, in Hashtable * @throws SQLException If an SQLException is propogated from the generic * query service * @throws InvalidRequestException throw if the externalURI is not a DataThing/unknown * @throws InternalProblemException */ public Hashtable getDataThingStandardMetadata(String externalURI) throws SQLException, InvalidRequestException, InternalProblemException; /** * Change the user-given name of a Thing in the MIR
* * replaces PersRep2 updateObjectName * * @param thingExternalURI The ID of the domain entity * @param newName The new name for the domain entity * @return void * @throws SQLException If an SQLException is propogated from the generic * query service * @throws UnknownUserException If an exception occurs * @throws InvalidRequestException If the thing does not exist */ public void updateThingName(String thingExternalURI, String newName) throws SQLException, InvalidRequestException; /** * Retrieves a DataThing XML value from the personal repository
* * Replaces PersRep2 getDomainEntity, getWFDefinitionXML and XX * * @param dtExternalURI The ExternalURI of the DataThing * @return value The value, either String or byte[] (if binary), as written. * @throws SQLException If an SQLException is propogated from the generic * query service * @throws InvalidRequestException If the ExternalURI is unknown */ public Object getDataThingValue(String dtExternalURI) throws SQLException, InvalidRequestException, InternalProblemException; /** * Retrieves a list of Things from the MIR given a userID (creator) and * localType * * Replaces PersRep2 getDomainEntityIDs, getWFInstanceIDs, and getWFDefinitionIDs * * @param userID The ID of the user whose Things require retrieval * @param localType MIR local type, e.g. 'DataThing', 'WFInstance', 'WFDefiniton', * 'WorkContext', 'Association', 'StringAnnotation', * 'XMLAnnotation' * @param properties Optional Hashtable of optional properties to match, currently * 'deleted'->'*' or 'null'. Ignored if null. * @return ExternalURIs The retrieved Thing ExternalURIs (Vector of String) * @throws SQLException If an SQLException is propogated from the generic * query service * @throws UnknownUserException If user is unknown * @throws InvalidRequestException If e.g. localType invalid */ public String[] getExternalURIsByUserAndLocalType(String userID, String localType, Hashtable properties) throws SQLException, UnknownUserException, InvalidRequestException, InternalProblemException; /** * Retrieves a list of Things from the MIR given a localType only
* * Intended as a placeholder to support sharing of WFDefinitions * * @param localType MIR local type, e.g. 'WFDefiniton' * @param properties Optional Hashtable of optional properties to match, currently * 'deleted'->'*' or 'null'. Ignored if null. * @return ExternalURIs The retrieved Thing ExternalURIs (Vector of String) * @throws SQLException If an SQLException is propogated from the generic * query service * @throws UnknownUserException If user is unknown * @throws InvalidRequestException If e.g. localType invalid */ public String[] getExternalURIsByLocalType(String localType, Hashtable properties) throws SQLException, InvalidRequestException, InternalProblemException; /*====================================================================== * WFDefinition */ /** * Stores a workflow definition in the MIR
* * Replaces PersRep2 storeWFDefinition * * Note that WFDefinition is a subclass of DataThing. So you can use * getDataThingStandardMetadata, updateThingName, getDataThingValue, etc. * * List using getExternalURIsByUserAndLocalType for localType 'WFDefinition'. * * @param createdByUserID The ID of the user * @param workContextExternalURI 'home' work context for DataThing * @param wfDefinitionXML The XML document of the workflow definition * @param wfDefinitionName The user given name of the workflow definition * @param externalURI An external URI for the 'original' version of this (optional; defaults to autogen LSID) * @param conceptURIs The concept URIs describing the domain entity * @param addUnknownConcepts Add unknown conceptURIs * @return ExternalURI The ExternalURI URI of the newly created object * @throws SQLException If an SQLException is propogated from the generic * query service * @throws UnknownUserException if the creating user is unknown * @throws UnknownPredicateException internal error (from add assoc.) * @throws UnknownConceptException internal error (from add assoc.) * @throws InvalidRequestException e.g. ill-formed XML * @throws DuplicateIDException externalURI already exists in MIR * @throws InternalProblemException */ public String addWFDefinition(String createdByUserID, String workContextExternalURI, String wfDefinitionXML, String wfDefinitionName, String externalURI, String [] conceptURIs, boolean addUnknownConcepts) throws SQLException, UnknownUserException, UnknownPredicateException, UnknownConceptException, InvalidRequestException, DuplicateIDException, InternalProblemException ; /*====================================================================== * WFInstance */ /** * Stores a WFInstance (WF provenance) record into MIR
* * Replaces PersRep2 storeWFProvenanceXML * * Note that a WFInstance is a subclass of DataThing. So you can use * getDataThingStandardMetadata, updateThingName, getDataThingValue, etc. * * List using getExternalURIsByUserAndLocalType for localType 'WFInstance'. * * @param createdByUserID The ID of the user * @param workContextExternalURI 'home' work context for DataThing * @param wfEnactorEndpoint The enactor SOAP endpoint URL for the workflow instance. * @param wfEnactorInstanceID The enactor's ID for the workflow instance that the provenace * record relates to * @param wfDefinitionExternalURI The ExternalURI of the workflow definition (must be local to MIR) * @param inputExternalURIs The DataThings used as inputs (must be local to MIR) * @param inputQualifiers Optional parallel array of predicateQualifiers for inputs; * must be same size of inputExternalURIs; null array gives null * as qualifiers. * @param instanceName user's name for WFInstance * @param externalURI An explicit external URI (optional; defaults to autogen LSID) * @param status The current status of the workflow * @param provenanceXML The current provenance record itself * @return ExternalURI for WFInstance * @throws SQLException If an SQLException is propogated from the generic * query service * @throws UnknownUserException if the creating user is unknown * @throws UnknownPredicateException internal error (from add assoc.) * @throws UnknownConceptException internal error (from add assoc.) * @throws InvalidRequestException e.g. ill-formed XML * @throws DuplicateIDException externalURI already exists in MIR * @throws InternalProblemException */ public String addWFInstance(String createdByUserID, String workContextExternalURI, String wfEnactorEndpoint, String wfEnactorInstanceID, String wfDefinitionExternalURI, String [] inputExternalURIs, String [] inputQualifiers, String instanceName, String externalURI, String status, String provenanceXML) throws SQLException, UnknownUserException, UnknownPredicateException, UnknownConceptException, InvalidRequestException, DuplicateIDException, InternalProblemException; /** * Updates the status and provenance record of a workflow instance
* * replaces PersRep2 updateWFProvenanceXML; note use of MIR ExternalURI as key * * increment's the DataThing's revision number (not part of LSID?!) * * this is an experimental placeholder - the only thing that makes a * destructive change to data in the repository. * * @param wfInstanceExternalURI The MIR ExternalURI of the workflow instance * @param status The status of the workflow * @param provenanceXML The provenance itself * @return void * @throws SQLException If an SQLException is propogated from the generic * query service * @throws UnknownUserException if the creating user is unknown * @throws UnknownPredicateException internal error (from add assoc.) * @throws UnknownConceptException internal error (from add assoc.) * @throws InvalidRequestException e.g. ill-formed XML */ public void updateWFInstance(String wfInstanceExternalURI, String status, String provenanceXML) throws SQLException, UnknownUserException, UnknownPredicateException, UnknownConceptException, InvalidRequestException; /** * Retrieves _standard_ metadata of a WFInstance
* * metadata returned in a hashtable, standard properties (keys) in addition to DataThing: * 'startTime', 'status', 'definedBy' (ExternalURI), 'enactorEndpoint' (URL), * * * @param lsid the WFInstance's ExternalURI * @return metaData The data thing's standard metadata, in Hashtable * @throws SQLException If an SQLException is propogated from the generic * query service * @throws InvalidRequestException throw if the lsid is not a DataThing/unknown * @throws InternalProblemException */ public Hashtable getWFInstanceStandardMetadata(String dtExternalURI) throws SQLException, InvalidRequestException, InternalProblemException; /** * Retrieves the associated datathing ExternalURIs given a workflow instance ID
* * Replaces PersRep2 getObjectIDsFromEntityWF * * Now (almost) a simple wrapper for getMetadataStandardMetadataBySimpleMatch * with predicateURI = '...hasInput' or '...hasOutput' as appropriate. * With the addition of a property 'inputQualifier' or 'outputQualifier' * from the association's predicateQualifier. * * The value of AssociationRole parameter can be 'INPUT' or 'OUTPUT' * denoting whether the associated DomainEntities were inputs to * the given WFInstance or outputs of it. * * results are returned as a Hashtable[] * * @param wfInstanceExternalURI The ExternalURI of the workflow instance * @param associationRole 'INPUT' or 'OUTPUT' * @return array of Association standard metadata (see getMetadataStandardMetadata) * @throws SQLException If an SQLException is propogated from the generic * query service * @throws UnknownPredicateException internal error * @throws UnknownConceptException internal error * @throws InvalidRequestException e.g. unknown wfInstanceExternalURI * @throws InternalProblemException */ public Hashtable[] getWFInstanceAssociationsStandardMetadata (String wfInstanceExternalURI, String associationRole) throws SQLException, UnknownPredicateException, UnknownConceptException, InvalidRequestException, InternalProblemException; /*====================================================================== * WorkContext */ /** * Get default/top-level work context for a user.
* * This is really just a stop-gap measure to get a version up and running. * Expect more sophisticated handling of WorkContexts soon. * * @param userID user * @return workContextExternalURI ExternalURI of user's root workcontext * @throws SQLException If an SQLException is propogated from the generic * query service * @throws UnknownUserException if the creating user is unknown */ public String getUserRootWorkContext(String userID) throws SQLException, UnknownUserException, InvalidRequestException, InternalProblemException; /** * Create a new WorkContext in the MIR
* * @param createdByUserID userID of creating User * @param parentWorkContextExternalURI 'home' work context for new workcontext * @param name name of workcontext (optional) * @param externalURI non-MIR URI of workcontext (optional; defaults to autogen LSID) * @return ExternalURI for workcontext (optional; defaults to autogen LSID) * @throws SQLException If an SQLException is propogated from the generic * query service * @throws UnknownUserException if the creating user is unknown * @throws InvalidRequestException if parentWorkContextExternalURI invalid * @throws InternalProblemException */ public String addWorkContext(String createdByUserID, String parentWorkContextExternalURI, String name, String externalURI) throws SQLException, UnknownUserException, InvalidRequestException, InternalProblemException; /*====================================================================== * ProxyThing */ /** * Create a new ProxyThing in the MIR
* * A ProxyThing has no metadata beyond a Thing. * * @param createdByUserID userID of creating User * @param workContextExternalURI 'home' work context for new ProxyThing * @param name name of ProxyThing (optional, default is null) * @param externalURI non-MIR URI of thing for which this is a proxy. * @return ExternalURI for workcontext * @throws SQLException If an SQLException is propogated from the generic * query service * @throws UnknownUserException if the creating user is unknown * @throws InvalidRequestException if parentWorkContextExternalURI invalid * @throws InternalProblemException */ public String addProxyThing(String createdByUserID, String workContextExternalURI, String name, String externalURI) throws SQLException, UnknownUserException, InvalidRequestException, InternalProblemException; /*====================================================================== * Collection */ /** * Create a new Collection in the MIR
* * @param createdByUserID userID of creating User * @param workContextExternalURI 'home' work context for new Collection * @param name name of Collection (optional, default is null) * @param externalURI non-MIR URI of Collection. (null defaults to auto- * generated MIR-specific LSID). * @param membersExternalURI non-MIR URI used to refer to the members of the * collection rather than to the collection itself. * (null defaults to auto-generated MIR-specific LSID) * @return ExternalURI for workcontext * @throws SQLException If an SQLException is propogated from the generic * query service * @throws UnknownUserException if the creating user is unknown * @throws InvalidRequestException if parentWorkContextExternalURI invalid * @throws InternalProblemException */ public String addCollection(String createdByUserID, String workContextExternalURI, String name, String externalURI, String membersExternalURI) throws SQLException, UnknownUserException, InvalidRequestException, InternalProblemException; /** * Retrieves _standard_ metadata of a Collection
* * metadata returned in a hashtable, standard properties (keys) in addition to Thing: * 'membersExternalURI' * * @param externalURI the Collection's externalURI * @return metaData The Collection's standard metadata, in Hashtable * @throws SQLException If an SQLException is propogated from the generic * query service * @throws InvalidRequestException throw if the externalURI is not a DataThing/unknown * @throws InternalProblemException */ public Hashtable getCollectionStandardMetadata(String externalURI) throws SQLException, InvalidRequestException, InternalProblemException; /*====================================================================== * GenericQuery */ /** * Executes a sql command against the MIR database.
* * just a placeholder at the moment, since mapping to/from * externalURIs is also necessary for this to be useful. * * @param sql the sql command to be executed * @return results the results generated by the the sql command * (as a single list of Strings) * @throws SQLException If an SQLException is propogated from the generic * query service */ public Vector doSqlQuery(String sql) throws SQLException, InvalidRequestException ; /*======================================================================*/ } //EOF