001package org.cleartk.clearnlp;
002
003import java.util.List;
004
005import org.apache.uima.jcas.JCas;
006import org.apache.uima.jcas.cas.TOP;
007import org.apache.uima.jcas.tcas.Annotation;
008
009import com.google.common.annotations.Beta;
010
011/**
012 * Defines common set of dependency graph data type operations used to convert to and query in
013 * the target type system
014 * 
015 * @author Lee Becker
016 *
017 */
018@Beta
019public interface DependencyOps<
020    NODE_TYPE extends TOP,
021    NODE_SPAN_TYPE extends Annotation,
022    ROOT_NODE_TYPE extends NODE_TYPE,
023    ROOT_NODE_SPAN_TYPE extends Annotation,
024    RELATION_TYPE extends TOP> {
025  
026  /**
027   * Selects the single root node within the annotation. Should error on more than one root node.
028   */
029  ROOT_NODE_TYPE selectRootNode(JCas jCas, Annotation coveringAnnotation);
030
031  /**
032   * Selects all dependency nodes within the annotation, excluding the root node.
033   * 
034   * Nodes should be ordered by their offsets. 
035   */
036  List<NODE_TYPE> selectNodes(JCas jCas, Annotation coveringAnnotation);
037
038  List<RELATION_TYPE> getHeadRelations(JCas jCas, NODE_TYPE node);
039  NODE_TYPE getHead(JCas jCas, RELATION_TYPE relation); 
040  String getLabel(JCas jCas, RELATION_TYPE relation); 
041  
042  /**
043   * Creates a new dependency node for the specified span
044   */
045  NODE_TYPE createNode(JCas jCas, NODE_SPAN_TYPE span);
046  ROOT_NODE_TYPE createRootNode(JCas jCas, ROOT_NODE_SPAN_TYPE span);
047  
048  /**
049   * Creates a relation between the two nodes.  If dealing with a type system where the relation is a separate object,
050   * this will likely create a new relation object.  For graphs that have the relation built into the node, this will likely
051   * just set labels on head and child relation fields
052   */
053  RELATION_TYPE createRelation(JCas jCas, NODE_TYPE head, NODE_TYPE child, String relation);
054  
055  /**
056   * Sets the head relations for a given node.  This is only important if the type system supports multi-head dependency parses
057   */
058  void setHeadRelations(JCas jCas, NODE_TYPE node, List<RELATION_TYPE> headRelations);
059  
060  /**
061   * Sets the head relations for a given node.  This is only important if the type system supports multi-child dependency parses
062   */
063  void setChildRelations(JCas jCas, NODE_TYPE node, List<RELATION_TYPE> childRelations);
064
065}