/*
 * 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.resource.metadata;

import org.apache.uima.analysis_engine.TypeOrFeature;

/**
 * A <code>Capability</code> defines an operation that an Resource can carry out. Each Capability
 * consists of the following information:
 * <ul>
 * <li>The output types and features that the Resource can produce in the CAS</li>
 * <li>The input types and features that are required</li>
 * <li>The Sofa names of input Sofas that are required</li>
 * <li>The Sofa names of output Sofas that the resource can produce</li>
 * <li>Preconditions that must be satisfied in order for processing to begin. In a text analysis
 * engine, the most common precondition is a check on the language of the document.</li>
 * </ul>
 * 
 * As with all {@link MetaDataObject}s, a <code>Capability</code> may or may not be modifiable. An
 * application can find out by calling the {@link #isModifiable()} method.
 * 
 * 
 */
public interface Capability extends MetaDataObject {
  Capability[] EMPTY_CAPABILITIES = new Capability[0];

  /**
   * Gets the description of this Capability.
   * 
   * @return the description of this Capability.
   */
  String getDescription();

  /**
   * 
   * Sets the description of this Capability.
   * 
   * @param aDescription
   *          aDescription the description of this Capability.
   */
  void setDescription(String aDescription);

  /**
   * Gets the inputs of this Capability.
   * 
   * @return an array of references to Types or Features in this Resource's Type System.
   */
  TypeOrFeature[] getInputs();

  /**
   * Gets the outputs of this Capability.
   * 
   * @return an array of references to Types or Features in this Resource's TypeSystem.
   */
  TypeOrFeature[] getOutputs();

  /**
   * Gets the inputs Sofa names of this Capability.
   * 
   * @return an array of strings representing the SofAName
   */
  String[] getInputSofas();

  /**
   * Gets the output Sofa names of this Capability.
   * 
   * @return an array of strings representing output SofA names
   */
  String[] getOutputSofas();

  /**
   * Retrieves the preconditions that must be satisfied in order for the Resource to begin
   * processing.
   * 
   * @return an unmodifiable list of {@link Precondition Precondition}s.
   */
  Precondition[] getPreconditions();

  /**
   * A convenience method that analyzes the preconditions of this <code>Capability</code> and
   * returns the ISO language identifiers that the Resource supports. This is only meaningful when
   * analyzing text documents.
   * 
   * @return an array of ISO language identifiers. An empty array means that the Resource claims to
   *         be language-independent.
   */
  String[] getLanguagesSupported();

  /**
   * A convenience method that analyzes the preconditions of this <code>Capability</code> and
   * returns the MIME types that the Resource can take as input.
   * 
   * @return an array of MIME types. This may be empty if the Resource does not declare MIME type
   *         preconditions.
   */
  String[] getMimeTypesSupported();

  /**
   * Sets the inputs of this Capability.
   * 
   * @param aInputs
   *          an array of references to Types or Features in this Resource's TypeSystem.
   */
  void setInputs(TypeOrFeature... aInputs);

  /**
   * Sets the outputs of this Capability.
   * 
   * @param aOutputs
   *          an array of references to Types or Features in this Resource's TypeSystem.
   */
  void setOutputs(TypeOrFeature... aOutputs);

  /**
   * Sets the input Sofa names.
   * 
   * @param aInputSofas
   *          an array of strings containing SofA names
   */
  /* Reserved for future use. */
  void setInputSofas(String... aInputSofas);

  /**
   * Sets the output Sofa names of this capability
   * 
   * @param aOutputSofas
   *          an array of strings containing SoFA name
   */
  void setOutputSofas(String... aOutputSofas);

  /**
   * Sets the <code>Precondition</code>s of this <code>Capability</code>.
   * 
   * @param aPreconditions
   *          an array of <code>Precondition</code> objects
   * 
   * @throws org.apache.uima.UIMA_UnsupportedOperationException
   *           if this <code>MetaDataObject</code> is not modifiable.
   */
  void setPreconditions(Precondition... aPreconditions);

  /**
   * A convenience method that sets the languages that this Resource supports. This is only
   * meaningful when text documents are analyzed.
   * <p>
   * Calling this method affects the preconditions of this <code>Capability</code>. All other
   * language support preconditions will be removed, but non-language related preconditions will be
   * unaffected.
   * 
   * @param aLanguageIDs
   *          an array of ISO language identifiers. An empty array means that the Resource claims to
   *          be language-independent.
   */
  void setLanguagesSupported(String... aLanguageIDs);

  /**
   * A convenience method that sets the MIME types that this Resource can take as input.
   * <p>
   * Calling this method affects the preconditions of this <code>Capability</code>. All other MIME
   * type preconditions will be removed, but other preconditions will be unaffected.
   * 
   * @param aMimeTypes
   *          an array of MIME types. This may be empty if the Resource does not declare MIME type
   *          preconditions.
   */
  void setMimeTypesSupported(String... aMimeTypes);

  /**
   * A convenience method that adds an input Type to this Capability.
   * 
   * @param aTypeName
   *          the fully qualified type name
   * @param aAllAnnotatorFeatures
   *          if true, indicates that this Capability requires as input all features of this type
   *          that are specified in the same AnalysisEngine descriptor. If false, features must be
   *          explicitly declared by calling {@link #addInputFeature(String)}.
   */
  void addInputType(String aTypeName, boolean aAllAnnotatorFeatures);

  /**
   * A convenience method that adds an input Feature to this Capability.
   * 
   * @param aFeatureName
   *          the fully qualified feature name
   */
  void addInputFeature(String aFeatureName);

  /**
   * A convenience method that adds an output Type to this Capability.
   * 
   * @param aTypeName
   *          the fully qualified type name
   * @param aAllAnnotatorFeatures
   *          if true, indicates that this Capability declares as output all features of this type
   *          that are specified in the same AnalysisEngine descriptor. If false, features must be
   *          explicitly declared by calling {@link #addOutputFeature(String)}.
   */
  void addOutputType(String aTypeName, boolean aAllAnnotatorFeatures);

  /**
   * A convenience method that adds an output Feature to this Capability.
   * 
   * @param aFeatureName
   *          the fully qualified feature name
   */
  void addOutputFeature(String aFeatureName);

  /**
   * A convenience method that adds an input Sofa name to this Capability.
   * 
   * @param aSofaName
   *          the sofa to add to the inputs
   */
  void addInputSofa(String aSofaName);

  /**
   * A convenience method that adds an output Sofa name to this Capability.
   * 
   * @param aSofaName
   *          the sofa to add as an output
   */
  void addOutputSofa(String aSofaName);

  /**
   * A convenience method that adds a supported language to this Capability.
   * 
   * @param aLanguage
   *          the ISO language identifier
   */
  void addSupportedLanguage(String aLanguage);

  /**
   * A convenience method that removes a supported language from this Capability.
   * 
   * @param aLanguage
   *          the ISO language identifier
   */
  void removeSupportedLanguage(String aLanguage);

}