/*
 * 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.aae.client;

import java.util.List;
import java.util.Map;

import org.apache.uima.aae.monitor.statistics.AnalysisEnginePerformanceMetrics;
import org.apache.uima.cas.CAS;
import org.apache.uima.cas.SerialFormat;
import org.apache.uima.collection.CollectionReader;
import org.apache.uima.collection.EntityProcessStatus;
import org.apache.uima.resource.ResourceInitializationException;
import org.apache.uima.resource.ResourceProcessException;
import org.apache.uima.resource.metadata.ProcessingResourceMetaData;

/**
 * A <code>UimaAsynchronousEngine</code> enables an application to send CASes for analysis to remote
 * UIMA AS service. It provides a high level API and hides the detail of the transport
 * implementation. The UIMA AS Client implementation uses JMS as its transport mechanism. Both
 * synchronous and asynchronous processing is supported. For synchronous processing an application
 * should call {@link #sendAndReceiveCAS(CAS)} method. For asynchronous processing the application
 * should call {@link #sendCAS(CAS)} method. Additionally, processing with a client side
 * <code>CollectionReader</code> is supported as well. The application first instantiates and
 * initializes the <code>CollectionReader</code> and registers it via
 * {@link #setCollectionReader(CollectionReader)} method. Once the <code>CollectionReader</code> is
 * registered, and {@link #initialize(Map)} method is called, the application may call
 * {@link #process()} method.
 * 
 * 
 * This API enables the application to dynamically deploy UIMA AS services that it intends to use
 * for processing. These services are deployed in a container and are collocated in the same JVM as
 * the application. The services are considered private and used exclusively by the application. To
 * deploy "private" services the application calls either {@link #deploy(String, Map)}
 * {@link #deploy(String[], Map)} method, where the first parameter is either a single AS deployment
 * descriptor or an array thereof. The application must deploy its "private" services *before*
 * calling {@link #initialize(Map)} method.
 * 
 * 
 * The application may stop the UIMA AS client in the middle of processing by calling
 * {@link #stop()} method.
 * 
 * 
 * Listeners can register with the <code>UimaAsynchronousEngine</code> by calling the
 * {@link #addStatusCallbackListener(UimaAsBaseCallbackListener)} method. These listeners receive
 * status callbacks during the processing. An exception to that is the synchronous processing via
 * {@link #sendAndReceiveCAS(CAS)} method. This method returns either a CAS containing results of
 * analysis or an exception. No callbacks are made while processing CASes synchronously.
 * 
 * An application may choose to implement parallelization of the processing, calling either
 * {@link #sendAndReceiveCAS(CAS)} or {@link #sendCAS(CAS)} methods from multiple threads.
 * 
 * 
 * 
 */
public interface UimaAsynchronousEngine {
  /**
   * @deprecated
   */
  public final String ApplicationContext = "ApplicationContext";
  
  /**
   * Name of an application that uses Uima AS client. The application provides it to the Uima AS client
   * in a Map which is an argument in {@link #initialize(Map)} .This name is used to register Uima AS 
   * client MBean with JMX. To make the name unique, provided string is prepended to a UUID to form 
   * ApplicationName_www_xxxx_yyyy_zzzz
   */
  public final String ApplicationName = "ApplicationName";

  /**
   * Broker URL the Uima AS client will use to communicate with Uima AS service. The application provides it 
   * to the Uima AS client in a Map which is an argument in {@link #initialize(Map)}. Required. If omitted, the
   * Uima AS client throws {@link ResourceInitializationException}
   */
  public final String ServerUri = "ServerURI";

  /**
   * Name of a queue where the Uima AS client sends JMS requests. The application provides it 
   * to the Uima AS client in a Map which is an argument in {@link #initialize(Map)}. Required. If omitted, the
   * Uima AS client throws {@link ResourceInitializationException}
   */
  public final String ENDPOINT = "Endpoint";

  /**
   * @deprecated use ENDPOINT instead
   */
  public final String Endpoint = "Endpoint";

  /**
   * Size of Cas pool to create. This parameter determines how many CASes can be processed concurrently.
   * The application provides it to the Uima AS client in a Map which is an argument in {@link #initialize(Map)}. Optional. 
   * If omitted, the Uima AS client will use 1 as a default. 
   */
  public final String CasPoolSize = "CasPoolSize";

  /**
   * @deprecated 
   */
  public final String ShadowCasPoolSize = "ShadowCasPoolSize";

  /**
   * @deprecated
   */
  public static final String ReplyWindow = "ReplyWindow";

  /**
   * CAS process timeout. The max amount of time allowed to process a CAS. The application provides it 
   * to the Uima AS client in a Map which is an argument in {@link #initialize(Map)}. Optional. If omitted, the
   * Uima AS client defaults to no timeout.
   */
  public static final String Timeout = "Timeout";

  /**
   * Collection Processing Complete timeout. The max amount of time allowed to process CPC request.The application 
   * provides it to the Uima AS client in a Map which is an argument in {@link #initialize(Map)}. Optional. If omitted, 
   * the Uima AS client defaults to no timeout.
   */
  public static final String CpcTimeout = "CpcTimeout";

  /**
   * GetMeta timeout. The max amount of time allowed to process GetMeta request.The application 
   * provides it to the Uima AS client in a Map which is an argument in {@link #initialize(Map)}. Optional. If omitted, 
   * the Uima AS client defaults to 60 seconds.
   */
  public static final String GetMetaTimeout = "GetMetaTimeout";

  /**
   * Path to the XSLT processor to use when processing a deployment descriptor. The application provides it to the Uima AS 
   * client via System property, either on a command line using -D, or explicitly by using java's 
   * System.setProperty(DD2SpringXsltFilePath,value). This path is required only if the Uima AS Client is used to deploy 
   * Uima AS service.
   */
  public static final String DD2SpringXsltFilePath = "DD2SpringXsltFilePath";

  /**
   * Saxon classpath to use when processing a deployment descriptor. The application provides it to the Uima AS client 
   * in a Map which is an argument in {@link #initialize(Map)}. This classpath is required only if the Uima AS Client is 
   * used to deploy Uima AS service.
   */
  /**
   * Saxon classpath to use when processing a deployment descriptor. The application provides it to the Uima AS 
   * client via System property, either on a command line using -D, or explicitly by using java's 
   * System.setProperty(SaxonClasspath,value). This path is required only if the Uima AS Client is used to deploy 
   * Uima AS service.
   */
  public static final String SaxonClasspath = "SaxonClasspath";

  /**
   * Debug flag to use when processing a deployment descriptor. If set, the dd2spring processor will not remove generated
   * spring configuration file on client exit. The application provides it to the Uima AS 
   * client via System property, either on a command line using -D, or explicitly by using java's 
   * System.setProperty(UimaEeDebug,value). This setting is only relevant if the Uima AS Client is used to deploy 
   * Uima AS service.
   */
  public static final String UimaEeDebug = "-uimaEeDebug";

  /**
   * Type of serialization to use when serializing CASes to remote Uima AS service. 
   * Valid serialization types are the string "xmi" (any case) or other (taken to be binary).
   * If this setting is omitted, the Uima AS client uses XMI as a default. 
   * The application provides it to the Uima AS client in a Map which is an argument in {@link #initialize(Map)}
   */
  public static final String SERIALIZATION_STRATEGY = "SerializationStrategy";
  
  /**
   * @deprecated
   */
  public static final String SerializationStrategy = "SerializationStrategy";

  /**
   * The userName for Message queuing connection if needed 
   */
  public static final String userName = null;
  
  /**
   * The password for Message queuing connection if needed
   */
  public static final String password = null;
  /**
   * @deprecated 
   */
  public static final String SharedConnection = "SharedConnection";

  /**
   * Flag to indicate whether or not the uima-as client should use
   * timer per CAS. The default is single timer for all outstanding
   * CASes.
   */
  public static final String TimerPerCAS = "TimerPerCAS";
  
  
  public static final String TargetSelectorProperty ="TargetServiceId";
  
  /**
   * Initializes UIMA asynchronous client using configuration parameters provided in a Map object.
   * It creates a connection to a service queue managed by a Broker as specified in the parameters.
   * A temporary reply queue is also created with a JMS listener attached to it. Once the
   * connections are made and the listener is started the method sends getMeta request to the UIMA
   * AS service and waits for a response. When the reply to getMeta is received the UIMA AS client
   * is fully initialized and notifies an application by calling 
   * {@link org.apache.uima.aae.client.UimaASStatusCallbackListener#initializationComplete(EntityProcessStatus)}
   * on the application listener.
   * 
   * @param anApplicationContext
   *          - configuration containing UIMA EE Service Broker URI, service queue name, timeout
   *          value, reply window size, and CAS Pool size.
   * 
   * @throws ResourceInitializationException init error
   */
  public void initialize(Map anApplicationContext) throws ResourceInitializationException;

  /**
   * Registers a <code>CollectionReader</code> instance to process a Collection. This method must be
   * called first, before calling {@link #process()} method.
   * 
   * @param aCollectionReader
   *          - instance of a <code>CollectionReader</code>
   * 
   * @throws ResourceInitializationException init error
   */
  public void setCollectionReader(CollectionReader aCollectionReader)
          throws ResourceInitializationException;

  /**
   * Registers application specific listener. Via this listener the application receives call-backs.
   * More than one listener can be added.
   * 
   * 
   * @param aListener
   *          - application listener object to add
   */
  public void addStatusCallbackListener(UimaAsBaseCallbackListener aListener);

  /**
   * Unregisters named application listener.
   * 
   * @param aListener
   *          - application listener to remove
   */
  public void removeStatusCallbackListener(UimaAsBaseCallbackListener aListener);

  /**
   * Stops the asynchronous client. Cleans up resources, drops connection to UIMA AS service queue
   * and stops listening on a response queue.
   * 
   * @throws Exception error
   */
  public void stop() throws Exception;

  /**
   * Not implemented
   * 
   * @return performance report
   */
  public String getPerformanceReport();

  /**
   * Initiates processing of a collection. This method should be only called after initialize() has
   * been called and an instance of a <code>CollectionReader</code> is provided via
   * {@link #setCollectionReader(CollectionReader)}. This method blocks until the <code>CollectionReader</code>
   * finishes processing the entire collection. Status of the processing can be obtained by
   * registering a listener with the
   * {@link #addStatusCallbackListener(UimaAsBaseCallbackListener)} method.
   * <p>
   * The method is synchronized to allow processing of only one collection at a time. The
   * application must wait with processing another collection until it receives notification via a
   * listener
   * {@link UimaASStatusCallbackListener#collectionProcessComplete(EntityProcessStatus aStatus)}
   * 
   * @throws ResourceProcessException
   *           - if there is a problem processing the Collection
   */
  public void process() throws ResourceProcessException;

  /**
   * Sends a given CAS for analysis to UIMA AS Service. This method may block if the client is
   * configured to use a reply window which prevents sending too many CASes to the service. Assuming
   * the window is large enough to send the CAS, this method returns as soon as the CAS is sent.
   * Before sending the CAS, a timer starts that will expire if a reply doesn't arrive in a given
   * interval.
   * 
   * @param aCAS
   *          - a CAS to analyze.
   * 
   * @return - returns a unique identifier associated with the sent CAS
   * @throws ResourceProcessException error
   */
  public String sendCAS(CAS aCAS) throws ResourceProcessException;
  
  /**
   * Sends a given CAS for analysis to a specific instance of UIMA AS Service. This method may block if the client is
   * configured to use a reply window which prevents sending too many CASes to the service. Assuming
   * the window is large enough to send the CAS, this method returns as soon as the CAS is sent.
   * Before sending the CAS, a timer starts that will expire if a reply doesn't arrive in a given
   * interval.
   * 
   * @param aCAS
   *          - a CAS to analyze.
   * @param targetServiceId 
   *          - Id of a service which should process the CAS         
   * 
   * @return - returns a unique identifier associated with the sent CAS
   * @throws ResourceProcessException error
   */
  public String sendCAS(CAS aCAS, String targetServiceId) throws ResourceProcessException;

  /**
   * Requests new CAS instance from a CAS pool. This method blocks until a free instance of CAS is
   * available in a CAS pool.
   * 
   * @return - new CAS instance fetched from the CAS pool
   * @throws Exception error
   */
  public CAS getCAS() throws Exception;

  /**
   * Sends a Collection Processing Complete (CPC) request to a UIMA AS Service and blocks waiting
   * for a reply. The method blocks until the service replies or a timeout occurs. Before returning,
   * this method will notify an application of completing the Collection Processing Complete request
   * using registered listener
   * 
   * @throws ResourceProcessException error
   */
  public void collectionProcessingComplete() throws ResourceProcessException;

  /**
   * Returns a <code>ProcessingResourceMetadata</code> received from the UIMA AS Service. The
   * metadata is obtained from the service during initialization.
   * 
   * returns - an ProcessingResourceMetadata received from an asynchronous Analysis Engine service,
   * or null if initialize() has not yet been called.
   * 
   * @throws ResourceInitializationException error
   * 
   * @return ProcessingResourceMetaData metadata
   */
  public ProcessingResourceMetaData getMetaData() throws ResourceInitializationException;

  /**
   * This synchronous method sends a given CAS to a UIMA AS service and waits for response. The
   * method either returns a CAS with the result of analysis or throws an exception. It doesn't use
   * call-backs through a registered application listener.
   * 
   * @param aCAS
   *          - a CAS to analyze.
   * @return - a unique id assigned to the CAS
   * @throws ResourceProcessException error
   */
  public String sendAndReceiveCAS(CAS aCAS) throws ResourceProcessException;
  /**
   * This synchronous method sends a given CAS to a UIMA AS service and waits for response. The
   * method either returns a CAS with the result of analysis or throws an exception. It doesn't 
   * use call-backs through a registered application listener. If there is
   * no exception, the method also returns per Analysis Engine performance breakdown for the CAS.
   * This breakdown can be used to identify how much time each AE took to process the CAS. 
   * 
   * @param aCAS - a CAS to analyze.
   * @param   componentMetricsList - empty list to be filled with per AE performance metrics
   * @return - a unique id assigned to the CAS
   * @throws ResourceProcessException error
   */
  public String sendAndReceiveCAS(CAS aCAS, List<AnalysisEnginePerformanceMetrics> componentMetricsList) throws ResourceProcessException;
  
  /**
   * This synchronous method sends a given CAS to a UIMA AS service and waits for response. The
   * method either returns a CAS with the result of analysis or throws an exception. It doesn't 
   * use call-backs through a registered application listener. If there is
   * no exception, the method also returns per Analysis Engine performance breakdown for the CAS.
   * This breakdown can be used to identify how much time each AE took to process the CAS. 
   * 
   * @param aCAS - a CAS to analyze.
   * @param   componentMetricsList - empty list to be filled with per AE performance metrics
   * @param targetServiceId - Id of a specific service which should process the CAS  
   * @return - a unique id assigned to the CAS
   * @throws ResourceProcessException error
   */
  public String sendAndReceiveCAS(CAS aCAS, List<AnalysisEnginePerformanceMetrics> componentMetricsList, String targetServiceId) throws ResourceProcessException;
  /**
   * Deploys a UIMA AS container and all services defined in the provided deployment descriptor.
   * The deployment is within the same JVM. 
   * Each deployment descriptor contains an assembly of related UIMA AS services. This method is
   * synchronous and will block until all UIMA AS services are completely deployed and initialized.
   * If there is a problem deploying any of the UIMA AS services the container is destroyed and
   * exception thrown.
   * 
   * @param aDeploymentDescriptor
   *          - a deployment descriptor to deploy in a container.
   * @param anApplicationContext
   *          - initialization parameters needed to configure the client and services
   * 
   * @return - the id of the container in which the UIMA AS services were deployed
   * 
   * @throws Exception
   *           - if there was a problem deploying the container or UIMA AS services.
   */
  public String deploy(String aDeploymentDescriptor, Map anApplicationContext) throws Exception;

  /**
   * Deploys a single UIMA AS container and all services defined in provided deployment descriptors.
   * The deployment is within the same JVM. 
   * Each deployment descriptor contains an assembly of related UIMA AS services. This method is
   * synchronous and will block until all UIMA AS services are completely deployed and initialized.
   * If there is a problem deploying any of the UIMA AS services the container is destroyed and
   * exception thrown.
   * 
   * @param aDeploymentDescriptorList
   *          - a list of deployment descriptors to deploy in a container.
   * @param anApplicationContext
   *          - initialization parameters needed to configure the client and services
   * 
   * @return - the id of the container in which the UIMA AS services were deployed
   * 
   * @throws Exception
   *           - if there was a problem deploying the container or UIMA AS services.
   */
  public String deploy(String[] aDeploymentDescriptorList, Map anApplicationContext)
          throws Exception;

  /**
   * Undeploys specified UIMA AS container and all services running within it. Each UIMA AS
   * container has a unique id assigned to it during the deploy phase. This method is synchronous
   * and will block until the container (and all services contained within it) is destroyed.
   * 
   * @param aSpringContainerId
   *          - an id of the container to be destroyed.
   * 
   * @throws Exception error
   */
  public void undeploy(String aSpringContainerId) throws Exception;

  /**
   * Undeploys specified UIMA AS container and all services running within it. Each UIMA AS
   * container has a unique id assigned to it during the deploy phase. This method is synchronous
   * and will block until the container (and all services contained within it) is destroyed.
   * 
   * @param aSpringContainerId
   *          - an id of the container to be destroyed.
   * @param stop_level stop
   * @throws Exception error
   */
  public void undeploy(String aSpringContainerId, int stop_level) throws Exception;

  /**
   * Returns serialization strategy for the remote service. All CASes will be serialized according
   * to the specified serialization. Either XMI or BINARY or COMPRESSED_BINARY_6
   * 
   * 
   * @return String type of serialization for CASes
   */
  public SerialFormat getSerialFormat();

  /**
   * Request Uima AS client to initiate sending Stop requests to a service for all outstanding CASes
   * awaiting reply.
   * 
   */
  public void stopProducingCases();

  /**
   * Request Uima AS client to initiate sending Stop request to a service for a given CAS id If the
   * service is a Cas Multiplier, it will stop producing new CASes, will wait until all child CASes
   * finish and finally returns the input CAS.
   * 
   * @param aCasReferenceId cas id
   */
  public void stopProducingCases(String aCasReferenceId);
}