IXArchADTQuery.java

package org.archstudio.xarchadt;

import java.io.Serializable;
import java.util.Collection;
import java.util.List;

import javax.xml.xpath.XPathException;

import org.eclipse.emf.common.util.URI;
import org.eclipse.jdt.annotation.NonNullByDefault;
import org.eclipse.jdt.annotation.Nullable;

@NonNullByDefault
public interface IXArchADTQuery {
	/**
	 * Determines if a given ObjRef is valid, that is, if there is an object associated with it.
	 * 
	 * @param ref
	 *            ObjRef to check.
	 * @return <CODE>true</CODE> if there is an associated object, <CODE>false</CODE> otherwise.
	 */
	public boolean isValidObjRef(ObjRef ref);

	/**
	 * Gets a reference to a child or a single value from an xArch element. Roughly equivalent to:
	 * baseObject.get[TypeOfThing](); So, if the object referred to by baseObjRef implements a method called
	 * <CODE>IDescription getDescription();</CODE> then that would be called here as:
	 * <CODE>ObjRef descriptionRef = (ObjRef)get(baseObjRef, "Description");</CODE> where baseObjRef is a reference to
	 * the base object, and the typeOfThing is shown as "Description".
	 * 
	 * @param baseObjRef
	 *            Reference to a base element containing an <CODE>get[typeOfThing]</CODE> method.
	 * @param typeOfThing
	 *            A string containing the type of thing to get. For instance, if the object referred to by baseObjRef
	 *            contains a method called <CODE>getDescription</CODE>, then typeOfThing would be "Description".
	 * @return A <CODE>Object</CODE> referring to the object gotten if the object returned is an xArch element;
	 *         otherwise a {@link Serializable} object. For instance, if <CODE>typeOfThing</CODE> refers to an attribute
	 *         or is "Value" (when <CODE>baseObjRef</CODE> refers to a simple type) then this function will return a
	 *         string.
	 */
	@Nullable
	public Serializable get(ObjRef baseObjRef, String typeOfThing);

	///**
	// * Gets a reference to a child from an xArch element, given the child's ID. Roughly equivalent to:
	// * baseObject.get[TypeOfThing](id); So, if the object referred to by baseObjRef implements a method called
	// * <CODE>IDescription getDescription(String id);</CODE> then that would be called here as:
	// * <CODE>ObjRef descriptionRef = get(baseObjRef, "Description", id);</CODE> where baseObjRef is a reference to the
	// * base object, and the typeOfThing is shown as "Description". ID remains a string.
	// * 
	// * @param baseObjRef
	// *            Reference to a base element containing an <CODE>get[typeOfThing]</CODE> method.
	// * @param typeOfThing
	// *            A string containing the type of thing to get. For instance, if the object referred to by baseObjRef
	// *            contains a method called <CODE>getDescription</CODE>, then typeOfThing would be "Description".
	// * @param id
	// *            Identifier of thing to get.
	// * @return An <CODE>ObjRef</CODE> referring to the object gotten.
	// */
	//public ObjRef get(ObjRef baseObjRef, String typeOfThing, String id);

	///**
	// * Gets a set of references to a set of children from an xArch element, given the children's IDs. Roughly equivalent
	// * to: baseObject.get[TypeOfThing]s(ids); So, if the object referred to by baseObjRef implements a method called
	// * <CODE>Collection getDescriptions(String[] id);</CODE> then that would be called here as:
	// * <CODE>ObjRef[] descriptionRefs = get(baseObjRef, "Description", ids);</CODE> where baseObjRef is a reference to
	// * the base object, and the typeOfThing is shown as "Description". IDs remains strings.
	// * 
	// * @param baseObjRef
	// *            Reference to a base element containing an <CODE>get[typeOfThing]s</CODE> method.
	// * @param typeOfThing
	// *            A string containing the type of thing to get. For instance, if the object referred to by baseObjRef
	// *            contains a method called <CODE>getDescriptions</CODE>, then typeOfThing would be "Description".
	// * @param ids
	// *            Identifiers of things to get.
	// * @return An array of <CODE>ObjRef</CODE>s referring to the objects gotten.
	// */
	//public List<ObjRef> getAll(ObjRef baseObjRef, String typeOfThing, List<String> ids);

	@Nullable
	public Serializable resolve(ObjRef objRef);

	/**
	 * Gets a set of references to a set of children from an xArch element. Roughly equivalent to:
	 * baseObject.getAll[TypeOfThing]s(ids); So, if the object referred to by baseObjRef implements a method called
	 * <CODE>Collection getAllDescriptions();</CODE> then that would be called here as:
	 * <CODE>ObjRef[] descriptionRefs = getAll(baseObjRef, "Description");</CODE> where baseObjRef is a reference to the
	 * base object, and the typeOfThing is shown as "Description".
	 * 
	 * @param baseObjRef
	 *            Reference to a base element containing an <CODE>getAll[typeOfThing]s</CODE> method.
	 * @param typeOfThing
	 *            A string containing the type of thing to get. For instance, if the object referred to by baseObjRef
	 *            contains a method called <CODE>getAllDescriptions</CODE>, then typeOfThing would be "Description".
	 * @return An array of <CODE>ObjRef</CODE>s referring to the objects gotten.
	 */
	public List<Serializable> getAll(ObjRef baseObjRef, String typeOfThing);

	/**
	 * Determines if one node in the XML tree is an ancestor of another. This method is more efficient than using the
	 * output of <CODE>getAllAncestors(...)</CODE>, since <CODE>getAllAncestors(...)</CODE> makes wrapper objects for
	 * each ancestor, and this one just looks at the underlying XML nodes.
	 * 
	 * @param childRef
	 *            The potential child node.
	 * @param ancestorRef
	 *            The potential ancestor node.
	 * @return <CODE>true</CODE> if the node referred to by <CODE>ancestorRef</CODE> is an ancestor of the node referred
	 *         to by <CODE>childRef</CODE>, <CODE>false</CODE> otherwise.
	 */
	public boolean hasAncestor(ObjRef childRef, ObjRef ancestorRef);

	/**
	 * Determines if a node in the XML tree is attached to the root.
	 * 
	 * @param childRef
	 *            The node to check.
	 * @return <CODE>true</CODE> if the node referred to by <CODE>childRef</CODE> is attached to the root node of the
	 *         document; (i.e. the root node is an ancestor of the node), <CODE>false</CODE> otherwise.
	 */
	public boolean isAttached(ObjRef childRef);

	/**
	 * Gets all the ancestors (in the XML tree) of a given target object.
	 * 
	 * @param targetObjRef
	 *            Reference to target object.
	 * @return Array of references to ancestors, in order starting with (and including) the target object, then its
	 *         parent, then its parent's parent, etc.
	 */
	public List<ObjRef> getAllAncestors(ObjRef targetObjRef);

	public List<ObjRef> getLineage(ObjRef targetObjRef);

	/**
	 * Gets the parent (in the XML tree) of a given target object.
	 * 
	 * @param targetObjRef
	 *            Reference to target object.
	 * @return A reference to its parent in the XML tree, or <CODE>null</CODE> if it has none.
	 */
	@Nullable
	public ObjRef getParent(ObjRef targetObjRef);

	///**
	// * Gets the <CODE>XArchADTPath</CODE> of the given element.
	// * 
	// * @param ref
	// *            Reference to the element whose path you want to get.
	// * @return <CODE>XArchADTPath</CODE> to that element.
	// */
	//public XArchADTPath getXArchADTPath(ObjRef ref);

	/**
	 * Gets an element by its ID within a given xArch tree. If no such element exists, returns <CODE>null</CODE>.
	 * 
	 * @param documentRootRef
	 *            Reference to the IXArch object that is the root of the tree to search.
	 * @param id
	 *            The ID to search for.
	 * @return reference to the object, or <CODE>null</CODE> if no such object exists.
	 * @exception IllegalArgumentException
	 *                if <CODE>documentRootRef</CODE> is invalid.
	 */
	@Nullable
	public ObjRef getByID(ObjRef documentRootRef, String id);

	/**
	 * Gets an element by its ID within ANY OPEN xArch tree. If no such element exists, returns <CODE>null</CODE>.
	 * 
	 * @param id
	 *            The ID to search for.
	 * @return reference to the object, or <CODE>null</CODE> if no such object exists.
	 */
	@Nullable
	public ObjRef getByID(String id);

	/**
	 * Resolves an href, as might be found in an XLink.
	 * 
	 * @param documentRootRef
	 *            Reference to the IXArch object that provides the context in which the href exists.
	 * @param href
	 *            The href to resolve. May be local or remote. <I>Note:</I> For this version of the library, hrefs must
	 *            be in the form <CODE>#id</CODE> or <CODE>http://....#id</CODE>
	 * @return Reference to the referenced (by the href) object, or <CODE>null</CODE>.
	 */
	@Nullable
	public ObjRef resolveHref(ObjRef documentRootRef, String href);

	//	/**
	//	 * Resolves an <CODE>XArchADTPath</CODE> in the context of the given
	//	 * document (in terms of an <CODE>ObjRef</CODE> to the top level xArch
	//	 * element of a document).
	//	 * 
	//	 * @param documentRootRef
	//	 *            Reference to the top-level element of the document within
	//	 *            which to resolve the <CODE>XArchADTPath</CODE>.
	//	 * @param XArchADTPath
	//	 *            <CODE>XArchADTPath</CODE> to resolve.
	//	 * @return <CODE>ObjRef</CODE> to the referenced element, or
	//	 *         <CODE>null</CODE> if the path cannot be resolved
	//	 */
	//	public ObjRef resolveXArchADTPath(ObjRef documentRootRef, XArchADTPath XArchADTPath);

	@Nullable
	public ObjRef getDocumentRootRef(ObjRef ref);

	@Nullable
	public String getTagName(ObjRef ref);

	@Nullable
	public String getContainingFeatureName(ObjRef ref);

	public String getTagsOnlyPathString(ObjRef ref);

	public IXArchADTPackageMetadata getPackageMetadata(String nsURI);

	public Collection<IXArchADTPackageMetadata> getAvailablePackageMetadata();

	public IXArchADTTypeMetadata getTypeMetadata(String nsURI, String typeName);

	public IXArchADTTypeMetadata getTypeMetadata(ObjRef objRef);

	public boolean isInstanceOf(@Nullable Serializable object, String sourceNsURI, String sourceTypeName);

	/**
	 * Determines if an object of the target type can be assigned to a variable of the source type. In other words,
	 * determines if the source type is the same as, or a supertype or superinterface of, the target type.
	 * 
	 * @param sourceNsURI
	 *            source namespace URI
	 * @param sourceTypeName
	 *            source type name
	 * @param targetNsURI
	 *            target namespace URI
	 * @param targetTypeName
	 *            target type name
	 * @return true if an object of the target type can be assigned to a variable of the source type
	 */
	public boolean isAssignable(String sourceNsURI, String sourceTypeName, String targetNsURI, String targetTypeName);

	public List<IXArchADTSubstitutionHint> getAllSubstitutionHints();

	public List<IXArchADTSubstitutionHint> getSubstitutionHintsForSource(String sourceNsURI, String sourceTypeName);

	public List<IXArchADTSubstitutionHint> getSubstitutionHintsForTarget(String targetNsURI, String targetTypeName);

	@Nullable
	public ObjRef getDocumentRootRef(URI uri);

	public Collection<URI> getOpenURIs();

	@Nullable
	public URI getURI(ObjRef ref);

	public byte[] serialize(URI uri);

	public String getXPath(ObjRef toObjRef);

	public List<ObjRef> resolveObjRefs(ObjRef contextObjRef, String xPath) throws XPathException;

	public List<Serializable> resolveSerializables(ObjRef contextObjRef, String xPath) throws XPathException;
}