uimaj-2.2.1-incubating/uimaj-core/src/main/java/org/apache/uima/analysis_engine/ResultSpecification.java

/*
 * 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
 * 
 *   http://www.apache.org/licenses/LICENSE-2.0
 * 
 * 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.uima.analysis_engine;

import java.io.Serializable;

import org.apache.uima.analysis_component.AnalysisComponent;
import org.apache.uima.cas.TypeSystem;
import org.apache.uima.resource.metadata.Capability;
import org.apache.uima.util.XMLizable;

/**
 * A <code>ResultSpecification</code> is a set of desired outputs from a Analysis Engine or
 * Annotator. Each output is a reference to either a {@link org.apache.uima.cas.Type} or a
 * {@link org.apache.uima.cas.Feature}.
 * <p>
 * Annotator implementations may, but are not required to, check the <code>ResultSpecification</code> 
 * passed as a parameter to their {@link AnalysisComponent#setResultSpecification(ResultSpecification)}},
 * and produce only those <code>Type</code>s and <code>Feature</code>s that are part of the 
 * ResultSpecification.  Annotators can call the {@link #containsType(String)} and
 * {@link #containsFeature(String)} to determine which types and features belong to this
 * ResultSpecification and should be produced.
 * <p>
 * ResultSpecifications are language enabled to allow different values to be set and returned, based
 * on a ISO language identifier. There are two styles of the get and add methods: one takes an
 * additional parameter specifying the language(s), the other doesn't have this parameter. Using the
 * one without the language parameter is equivalent to using the "x-unspecified" language. The
 * functions that add ResultSpecifications can do this for multiple languages at once because the
 * language parameter is an array of strings. The functions to retrieve a ResultSpecification
 * specify one particular language.
 * <p>
 * If you query the ResultSpecification with a language with a country code (e.g. en-US), results
 * for the base language (en) will be returned as well.
 * 
 */
public interface ResultSpecification extends XMLizable, Serializable, Cloneable {
  /**
   * Retrieves the Types and Features that the AnalysisEngine or Annotator is requested to produce
   * for the default language x-unspecified.
   * 
   * @return an array of {@link TypeOrFeature} objects that define the result types and features for
   *         the language x-unspecified.
   */
  public TypeOrFeature[] getResultTypesAndFeatures();

  /**
   * Retrieves the Types and Features that the AnalysisEngine or Annotator is requested to produce
   * for the specified language.
   * 
   * @return an array of {@link TypeOrFeature} objects that define the result types and features for
   *         the specified language.
   */
  public TypeOrFeature[] getResultTypesAndFeatures(String language);

  /**
   * Sets the Types and Features that the AnalysisEngine or Annotator is requested to produce for
   * the language x-unspecified.
   * 
   * @param aTypesAndFeatures
   *          an array of {@link TypeOrFeature} objects that define the result types and features
   *          for the language x-unspecified.
   */
  public void setResultTypesAndFeatures(TypeOrFeature[] aTypesAndFeatures);

  /**
   * Sets the Types and Features that the AnalysisEngine or Annotator is requested to produce for
   * the specified languages.
   * 
   * @param aTypesAndFeatures
   *          an array of {@link TypeOrFeature} objects that define the result types and features
   *          for the specified languages.
   * 
   * @param aLanguageIDs
   *          an array of ISO language identifiers.
   */
  public void setResultTypesAndFeatures(TypeOrFeature[] aTypesAndFeatures, String[] aLanguageIDs);

  /**
   * Adds a Result Type or Feature to this <code>ResultSpecification</code> for the language
   * x-unspecified. If the current ToF is already contained in the result spec, the language
   * specification for this ToF will be replaced with x-unspecified.
   * 
   * @param aTypeOrFeature
   *          the Type or Feature to add for the language x-unspecified
   */
  public void addResultTypeOrFeature(TypeOrFeature aTypeOrFeature);

  /**
   * Adds a Result Type or Feature to this <code>ResultSpecification</code> for the specified
   * languages. If the current ToF is already contained in the result spec, the language
   * specification for this ToF will be replaced with the specified languages.
   * 
   * @param aTypeOrFeature
   *          the Type or Feature to add for the specified languages
   * 
   * @param aLanguageIDs
   *          an array of ISO language identifiers.
   */
  public void addResultTypeOrFeature(TypeOrFeature aTypeOrFeature, String[] aLanguageIDs);

  /**
   * Adds an Type to this <code>ResultSpecification</code> for the language x-unspecified.
   * 
   * If the current Type is already contained in the result spec, the language specification for
   * this Type will be replaced with x-unspecified.
   * 
   * @param aTypeName
   *          the name of the Type to add for the language x-unspecified
   * @param aAllAnnotatorFeatures
   *          whether all features of this type should also be produced
   */
  public void addResultType(String aTypeName, boolean aAllAnnotatorFeatures);

  /**
   * Adds an Type to this <code>ResultSpecification</code> for the specified languages.
   * 
   * If the given Type is already contained in the result spec, the languages specificied will be
   * added to those already associated with the Type in this ResultSpec.
   * 
   * @param aTypeName
   *          the name of the Type to add for the specified languages
   * @param aAllAnnotatorFeatures
   *          whether all features of this type should also be produced
   * @param aLanguageIDs
   *          an array of ISO language identifiers.
   */
  public void addResultType(String aTypeName, boolean aAllAnnotatorFeatures, String[] aLanguageIDs);

  /**
   * Adds a Feature to this <code>ResultSpecification</code> for the language x-unspecified.
   * 
   * If the given Type is already contained in the result spec, the languages specificied will be
   * added to those already associated with the Type in this ResultSpec.
   * 
   * @param aFullFeatureName
   *          the fully-qualified name of the Feature to add for the language x-unspecified
   */
  public void addResultFeature(String aFullFeatureName);

  /**
   * Adds a Feature to this <code>ResultSpecification</code> for the specified languages.
   * 
   * If the current Feature is already contained in the result spec, the language specification for
   * this Feature will be replaced with the specified languages.
   * 
   * @param aFullFeatureName
   *          the fully-qualified name of the Feature to add for the specified languages
   * 
   * @param aLanguageIDs
   *          an array of ISO language identifiers.
   */
  public void addResultFeature(String aFullFeatureName, String[] aLanguageIDs);

  /**
   * Compiles this <code>ResultSpecification</code> using a specific {@link TypeSystem}. This
   * allows the {@link #containsType(String)} and {@link #containsFeature(String)} methods to
   * properly consider the inheritance of types and to expand features when this
   * <code>ResultSpecification</code> contains Types with <code>allAnnotatorFeatures</code> set
   * to true.
   * <p>
   * This method is called automatically by the Analysis Engine. Annotators and Applications do not
   * need to call it.
   * 
   * @param aTypeSystem
   *          the Type System used to determine which features belong to each Type
   */
  public void compile(TypeSystem aTypeSystem);

  /**
   * Determines whether this <code>ResultSpecification</code> contains the specified Type for the
   * language x-unspecified.
   * 
   * @param aTypeName
   *          the name of the type
   * 
   * @return true if and only if this <code>ResultSpecification</code> contains the type with name
   *         <code>aTypeName</code>.
   */
  public boolean containsType(String aTypeName);

  /**
   * Determines whether this <code>ResultSpecification</code> contains the specified Type for the
   * specified language
   * 
   * @param aTypeName
   *          the name of the type
   * @param aLanguage
   *          the language to search for
   * 
   * @return true if and only if this <code>ResultSpecification</code> contains the type with name
   *         <code>aTypeName</code> for the specified language.
   */
  public boolean containsType(String aTypeName, String aLanguage);

  /**
   * Determines whether this <code>ResultSpecification</code> contains the specified Feature for
   * the language x-unspecified.
   * 
   * @param aFullFeatureName
   *          the fully-qualified name of the feature, in the form MyTypeName:MyFeatureName.
   * 
   * @return true if and only if this <code>ResultSpecification</code> contains the feature with
   *         name <code>aFullFeatureName</code>.
   */
  public boolean containsFeature(String aFullFeatureName);

  /**
   * Determines whether this <code>ResultSpecification</code> contains the specified Feature for
   * the specified language.
   * 
   * @param aFullFeatureName
   *          the fully-qualified name of the feature, in the form MyTypeName:MyFeatureName.
   * @param aLanguage
   *          the language to search for
   * 
   * @return true if and only if this <code>ResultSpecification</code> contains the feature with
   *         name <code>aFullFeatureName</code> for the specified language.
   */
  public boolean containsFeature(String aFullFeatureName, String aLanguage);

  /**
   * Adds the output types and features from the specified capabilities to this
   * <code>ResultSpecification</code>.
   * 
   * @param aCapabilities
   *          capabilities to add
   */
  public void addCapabilities(Capability[] aCapabilities);

  /**
   * Adds either outputs or inputs from the specified capabilities to this
   * <code>ResultSpecification</code>.
   * 
   * @param aCapabilities
   *          capabilities to add
   * @param aOutputs
   *          true to add the output types/features to this ResultSpecification, false to add the
   *          input types/features to this ResultSpecification.
   */
  public void addCapabilities(Capability[] aCapabilities, boolean aOutputs);

  /**
   * removes the specified TypeOrFeature from this <code>ResultSpecification</code>.
   * 
   * @param aTypeOrFeature
   *          the Type or Feature to remove
   */
  public void removeTypeOrFeature(TypeOrFeature aTypeOrFeature);

  /**
   * create a copy of the current object
   * 
   * @return Object returns a copy of the current object
   */
  public Object clone();

}