Class VinciTAP


  • public class VinciTAP
    extends java.lang.Object
    Vinci Proxy to remote Cas Processor vinci service. This component is used for both local( managed) and remote ( unmanaged) Cas Processors. Its main purpose is to invoke remote APIs on Cas Processors running as vinci services. It serializes data contained in the Cas into XCAS and sends it to the service. It desiralizes data from XCAS returned from the service back into the Cas.
    • Constructor Summary

      Constructors 
      Constructor Description
      VinciTAP()
      Instantiates a new vinci TAP.
    • Method Summary

      All Methods Static Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      static CasData addKeysToDataCas​(CasData dataCas, AFrame aFrame)
      Appends keys (types) from XCAS to provided CasData instance doing conversions of ':' in WF keys to '_colon_' and '-' to '_dash_' to enforce UIMA compliance.
      CasData[] analyze​(CasData[] aCasList, ProcessTrace aPT, java.lang.String aResourceName)
      Main routine that sends requests to remote vinci services.
      CasData analyze​(CasData aCas, ProcessTrace aPT, java.lang.String aResourceName)
      Performs Analysis of the CAS by the remote vinci service Cas Processor.
      void batchProcessComplete()
      Let the remote service now that end of batch marker has been reached, the notification is one-way meaning the CPE does not expect anything back from the service.
      void collectionProcessComplete()
      Notify the remote service that the CPE reached end of processing.
      void connect​(java.lang.String aServiceName)
      Connects to external service using service name as a way to locate it.
      void connect​(java.lang.String aHost, int aPort)
      Connects the proxy to Cas Processor running as a vinci service on a given host and port number.
      private void dropNamedTypes​(AFrame aKeyFrame, java.lang.String[] aDropKeyList)
      Drop named types.
      private static void dumpFeatures​(CasData aCAS)
      Prints to stdout contents of a given CasData instance.
      ProcessingResourceMetaData getAnalysisEngineMetaData()
      Returns Cas Processor metadata as it is returned from the remote Cas Processor running as vinci service.
      private FeatureStructure getDocTextFeatureStructure​(CasData aCasData)
      Gets the CasData FeatureStructure representing the document text, if any.
      java.lang.String getServiceHost()
      Returns host where the service is running.
      int getServicePort()
      Returns port of the service this proxy is connected to.
      java.lang.String getVNSHost()
      Returns VNS Host.
      java.lang.String getVNSPort()
      Returns VNS Port.
      boolean isConnected()
      Returns status of the vinci connection.
      private static boolean isText​(java.lang.String feature)
      Returns true if a given feature represents any of the content (SoFa) types.
      private void produceXCASRequestFrame​(CasData aCasData, AFrame dataFrame, java.lang.String[] aDropKeyList)
      Produces XCas from a given Cas.
      AFrame sendAndReceive​(AFrame aFrame)
      Send a given Vinci Frame to the remote vinci service and return result.
      void setContentTag​(java.lang.String aContentTag)
      Defines subject of analysis.
      void setKeys2Drop​(java.lang.String[] aKeys2Drop)
      Defines types as array that will not be sent to the Cas Processor service.
      void setTimeout​(int aTimeout)
      Define the max time in millis the proxy will wait for response from remote service.
      void setTimer​(UimaTimer aTimer)
      Defines a custom timer to use for stats.
      void setVNSHost​(java.lang.String aVNSHost)
      Sets the VNS host this proxy will use to locate service.
      void setVNSPort​(java.lang.String aVNSPort)
      Sets the VNS port this proxy will use to locate service.
      boolean shutdown​(boolean shutdownService, boolean aDoSendNotification)
      Conditionally sends the shutdown request to managed (local) vinci service.
      private void testAndReconnect()
      Test and reconnect.
      private void waitForServiceShutdown()
      Waits for local/managed service to shutdown.
      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
    • Field Detail

      • serviceHost

        private java.lang.String serviceHost
        The service host.
      • servicePort

        private java.lang.String servicePort
        The service port.
      • fencedProcessPID

        private java.lang.String fencedProcessPID
        The fenced process PID.
      • vnsHost

        private java.lang.String vnsHost
        The vns host.
      • vnsPort

        private java.lang.String vnsPort
        The vns port.
      • serviceName

        private java.lang.String serviceName
        The service name.
      • timeout

        private int timeout
        The timeout.
      • totalCasToFrameTime

        private long totalCasToFrameTime
        The total cas to frame time.
      • totalAnnotationTime

        private long totalAnnotationTime
        The total annotation time.
      • totalFrameToCasTime

        private long totalFrameToCasTime
        The total frame to cas time.
      • totalSerializeTime

        private long totalSerializeTime
        The total serialize time.
      • totalDeSerializeTime

        private long totalDeSerializeTime
        The total de serialize time.
      • totalRoundTripTime

        private long totalRoundTripTime
        The total round trip time.
      • uimaTimer

        private UimaTimer uimaTimer
        The uima timer.
      • contentTag

        private java.lang.String contentTag
        The content tag.
      • keys2Drop

        private java.lang.String[] keys2Drop
        The keys 2 drop.
      • vinciCasDataConverter

        private VinciCasDataConverter vinciCasDataConverter
        The vinci cas data converter.
    • Constructor Detail

      • VinciTAP

        public VinciTAP()
        Instantiates a new vinci TAP.
    • Method Detail

      • setContentTag

        public void setContentTag​(java.lang.String aContentTag)
        Defines subject of analysis.
        Parameters:
        aContentTag - - subject of analysis
      • setTimer

        public void setTimer​(UimaTimer aTimer)
        Defines a custom timer to use for stats.
        Parameters:
        aTimer - - custom timer
      • setKeys2Drop

        public void setKeys2Drop​(java.lang.String[] aKeys2Drop)
        Defines types as array that will not be sent to the Cas Processor service.
        Parameters:
        aKeys2Drop - - array of types excluded from the request
      • connect

        public void connect​(java.lang.String aHost,
                            int aPort)
                     throws java.net.ConnectException
        Connects the proxy to Cas Processor running as a vinci service on a given host and port number.
        Parameters:
        aHost - - name of the host where the service is running
        aPort - - port number where the service listens for requests
        Throws:
        java.net.ConnectException - wraps Exception or unable to connect
      • setTimeout

        public void setTimeout​(int aTimeout)
        Define the max time in millis the proxy will wait for response from remote service.
        Parameters:
        aTimeout - - number of millis to wait
      • connect

        public void connect​(java.lang.String aServiceName)
                     throws ServiceConnectionException
        Connects to external service using service name as a way to locate it.
        Parameters:
        aServiceName - - name of the service
        Throws:
        ServiceConnectionException - the service connection exception
      • addKeysToDataCas

        public static CasData addKeysToDataCas​(CasData dataCas,
                                               AFrame aFrame)
                                        throws java.lang.Exception
        Appends keys (types) from XCAS to provided CasData instance doing conversions of ':' in WF keys to '_colon_' and '-' to '_dash_' to enforce UIMA compliance.
        Parameters:
        dataCas - - instance of CasData where the keys will be appended
        aFrame - - source of keys (data)
        Returns:
        - modified CasData
        Throws:
        java.lang.Exception - passthru
      • dumpFeatures

        private static void dumpFeatures​(CasData aCAS)
        Prints to stdout contents of a given CasData instance.
        Parameters:
        aCAS - the a CAS
      • produceXCASRequestFrame

        private void produceXCASRequestFrame​(CasData aCasData,
                                             AFrame dataFrame,
                                             java.lang.String[] aDropKeyList)
                                      throws java.lang.Exception
        Produces XCas from a given Cas. It selectively copies features from the Cas excluding those types that are defined in a given dropKeyList.
        Parameters:
        aCasData - - Cas for which XCAS is built
        dataFrame - - XCas frame for data
        aDropKeyList - - list of types to exclude from XCas
        Throws:
        java.lang.Exception - passthru
      • isText

        private static boolean isText​(java.lang.String feature)
        Returns true if a given feature represents any of the content (SoFa) types.
        Parameters:
        feature - - type to check
        Returns:
        - true if SoFa, false otherwise
      • dropNamedTypes

        private void dropNamedTypes​(AFrame aKeyFrame,
                                    java.lang.String[] aDropKeyList)
        Drop named types.
        Parameters:
        aKeyFrame - the a key frame
        aDropKeyList - the a drop key list
      • analyze

        public CasData[] analyze​(CasData[] aCasList,
                                 ProcessTrace aPT,
                                 java.lang.String aResourceName)
                          throws ServiceException,
                                 ServiceConnectionException
        Main routine that sends requests to remote vinci services. Each Cas in the list is placed in the request frame in its own DATA frame. For each Cas, this routine create a seperate DATA frame. The DATA frame contains types and data that are required by the annotator. For efficiency, the dropKeyList array can be defined with types that will be omitted from the DATA frame. These keys are not required by the annotator thus it is waste of bandwidth to include them in the request.
        Parameters:
        aCasList - - a list of Cas to send to service for analysis
        aPT - - Process Trace object to aggrate time and stats
        aResourceName - - name of the Cas Processor
        Returns:
        - List of Cas instances containing results of analysis
        Throws:
        ServiceException - - passthru, wraps Exception
        ServiceConnectionException - passthru
      • batchProcessComplete

        public void batchProcessComplete()
                                  throws ResourceServiceException
        Let the remote service now that end of batch marker has been reached, the notification is one-way meaning the CPE does not expect anything back from the service.
        Throws:
        ResourceServiceException - the resource service exception
      • collectionProcessComplete

        public void collectionProcessComplete()
                                       throws ResourceServiceException
        Notify the remote service that the CPE reached end of processing. Wait for response from the service before returning. This ensures that the request is accepted and the desired logic handling end of processing has completed.
        Throws:
        ResourceServiceException - wraps Exception
      • shutdown

        public boolean shutdown​(boolean shutdownService,
                                boolean aDoSendNotification)
        Conditionally sends the shutdown request to managed (local) vinci service. This routine should not terminate services deployed as remote (unmanaged). This routine does not verify that the service shut itself down. It does not even wait for response. It is up to the service to clean itself up and terminate.
        Parameters:
        shutdownService - - flag indicating if a shutdown command should be sent to the service
        aDoSendNotification - - indicates whether or not to sent CollectionProcessComplete frame to service
        Returns:
        - true if shutdown message has been sent without error, false otherwise
      • waitForServiceShutdown

        private void waitForServiceShutdown()
        Waits for local/managed service to shutdown. If we dont allow the service time to cleanly terminate, sometimes it just lingers. Since the shutdown command sent in shuthdown() method is one-way call, it was immediately followed by the connection close. That caused an exception on the service side, preventing it from clean exit. So here we just wait until the connection no longer exists and then close it on this side.
      • isConnected

        public boolean isConnected()
        Returns status of the vinci connection.
        Returns:
        - true if connection is valid, false otherwise
      • setVNSPort

        public void setVNSPort​(java.lang.String aVNSPort)
        Sets the VNS port this proxy will use to locate service.
        Parameters:
        aVNSPort - - vns port to use
      • setVNSHost

        public void setVNSHost​(java.lang.String aVNSHost)
        Sets the VNS host this proxy will use to locate service.
        Parameters:
        aVNSHost - - name of the VNS host
      • getServicePort

        public int getServicePort()
        Returns port of the service this proxy is connected to.
        Returns:
        - service port
      • getServiceHost

        public java.lang.String getServiceHost()
        Returns host where the service is running.
        Returns:
        host name of the machine where the service is running
      • getVNSPort

        public java.lang.String getVNSPort()
        Returns VNS Port.
        Returns:
        VNS port
      • getVNSHost

        public java.lang.String getVNSHost()
        Returns VNS Host.
        Returns:
        VNS Host
      • getDocTextFeatureStructure

        private FeatureStructure getDocTextFeatureStructure​(CasData aCasData)
        Gets the CasData FeatureStructure representing the document text, if any. Currently, this must be one of the first two FSs in the CasData.
        Parameters:
        aCasData - CasData containing feature structures
        Returns:
        FeatureStructure representing document text, null if none