You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@uima.apache.org by re...@apache.org on 2022/04/28 19:05:43 UTC
[uima-async-scaleout] 01/01: [NO JIRA] Convert readme and release notes to markdown - and move version-specific stuff to release notes and general stuff to the README
This is an automated email from the ASF dual-hosted git repository.
rec pushed a commit to branch no-jira-readme-to-markdown
in repository https://gitbox.apache.org/repos/asf/uima-async-scaleout.git
commit 5d01a85ce3f449fa6975a501cb3a09b58c322fe3
Author: Richard Eckart de Castilho <re...@apache.org>
AuthorDate: Thu Apr 28 21:05:36 2022 +0200
[NO JIRA] Convert readme and release notes to markdown - and move version-specific stuff to release notes and general stuff to the README
---
README | 495 -----------------------------------------------------
README.md | 469 ++++++++++++++++++++++++++++++++++++++++++++++++++
RELEASE_NOTES.html | 81 ---------
RELEASE_NOTES.md | 75 ++++++++
4 files changed, 544 insertions(+), 576 deletions(-)
diff --git a/README b/README
deleted file mode 100644
index d60acb19..00000000
--- a/README
+++ /dev/null
@@ -1,495 +0,0 @@
- Apache UIMA Asynchronous Scaleout (UIMA-AS) Version 2.10.3 README
- ----------------------------------------------------------------
-
-0. Building from the Source Distribution
-========================================
-
-We use Maven 3.3.+ for building; download this if needed,
-and set the environment variable MAVEN_OPTS to -Xmx800m -XX:MaxPerSize-256m.
-
-Then build from the directory containing this README by issuing the command
- mvn clean install.
-
-This builds everything except the ...source-release.zip file. If you want that,
-change the command to
-
- mvn clean install -Papache-release
-
-Look for the result in the two artifacts:
- target/uima-as-[version]-source-release.zip (if run with -Papache-release) and
- target/uima-as-[version]-bin.zip (or ...tar.gz)
-
-If your maven build fails with strange errors try running maven with an update flag
-like this:
-
- mvn -U clean install
-
-Note that a build with -U option takes much longer to finish.
-
-For more details, please see http://uima.apache.org/building-uima.html
-
-1. What's New in 2.10.3
-======================
- - Modified client code to assign unique ClientID to broker connection
- - Fixed ClassCastException when async aggregate initializes delegate with JMS Service Descriptor
- - Fixed broken classpath and logging for UIMA-AS run configurations
-
-1.1 Contents of Apache UIMA-AS binary distribution
---------------------------------------------------
-
-The Apache UIMA-AS binary distribution includes
- - Apache UIMA Java SDK version 2.10.2
- - Apache UIMA Asynchronous Scaleout extensions
- - Saxon
- - Apache ActiveMQ version 5.15.2
- - Spring Framework version 4.3.9
- - XMLBeans
-
-It includes the base UIMA binary distribution which it depends on.
-
-UIMA-AS components, in addition to those that come with base UIMA include:
-
- shell scripts:
- --------------
-
- bin/startBroker.sh/bat: starts the ActiveMQ broker, which must be running before
- UIMA AS services can be deployed.
- bin/deployAsyncService.sh/bat: deploys an AnalysisEngine as a UIMA-AS
- service. Takes one or more UIMA-AS Deployment Descriptors as arguments.
- bin/runRemoteAsyncAE.sh/bat: Calls a UIMA-AS service. Takes arguments specifying the
- location of the service, and an optional CollectionReader descriptor file used to
- obtain the CASes to be processed by the service.
-
- documentation:
- --------------
-
- docs/d/uima_async_scaleout.pdf: UIMA-AS documentation, including the specification
- for the deployment descriptor file syntax.
-
- examples:
- ---------
-
- examples/deploy/as/... (Sample Deployment Descriptors)
- Deploy_RoomNumberAnnotator.xml: Deploys Room Number Annotator Primitive AE
- Deploy_MeetingDetectorTAE.xml: Deploys Meeting Detector Aggregate AE with all
- delegates in the same JVM.
- Deploy_MeetingDetectorTAE_Whiteboard.xml: Deploys Meeting Detector Aggregate AE
- using the whiteboard Flow Controller.
- Deploy_MeetingDetectorTAE_RemoteRoomNumber.xml: Deploys Meeting Detector Aggregate AE
- that uses remotely deployed RoomNumberAnnotator.
- Deploy_MeetingDetectorTAE_3MeetingAnnotator.xml: Deploys Meeting Detector Aggregate AE
- with three instances of the MeetingAnnotator component.
- Deploy_MeetingDetectorTAE_Sync_3Instances.xml: Deploys 3 instances of the
- Meeting Detector as a Synchronous Aggregate (meaning the delegate AEs do not each
- get their own input queue).
- Deploy_MeetingAnnotator.xml: Deploys C++ Meeting Annotator. Note: requires
- installation of uimacpp SDK into $UIMA_HOME.
-
- MeetingFinderAggregate.xml: Aggregate descriptor that use the same components as the
- CPE examples MeetingFinderCPE* in base UIMA.
- Deploy_MeetingFinder.xml: Deploys MeetingFinderAggregate illustrating scalability and
- error handling similar to the CPM examples; see Section 4 on migration below.
-
- descriptors:
- ------------
-
- descriptors/as/... (Other Sample Descriptors for use with UIMA AS)
- MeetingDetectorAsyncAE.xml: Specifier that can be used to call a UIMA AS
- Service from an existing UIMA application; see Section 2.5 below.
-
-
-2. Installation and Setup
-=========================
-
-2.1 Supported Platforms
------------------------
-
-Apache UIMA-AS requires Java version 8 or later; it has been tested with Sun/Oracle Java 8 and IBM 8.
-
-Running the Eclipse plugin tooling for UIMA requires you start Eclipse using a Java 8 or later, as well.
-
-The supported platforms are: Windows, Linux, and Mac OS X. Other platforms and Java (8+)
-implementations should work, but have not been significantly tested.
-
-
-2.2. Environment Variables
---------------------------
-
-After you have unpacked the UIMA AS distribution, you must perform the following
-environment variable settings (the same as for normal Apache UIMA setup):
-
- * Set JAVA_HOME to the directory of your JRE installation you would like to use for UIMA.
- * Set UIMA_HOME to the apache-uima-as directory of your unpacked Apache UIMA distribution
- * Append UIMA_HOME/bin to your PATH
-
- Note: The Mac OS X operating system has special procedures for setting up global environment
- variables; see http://developer.apple.com/qa/qa2001/qa1067.html for how to do this.
-
-2.3 Running the Setup Script
-----------------------------
-
-You must run the script UIMA_HOME/bin/adjustExamplePaths.bat (or .sh). This updates
-paths in the examples based on the actual UIMA_HOME directory path.
-
-2.4 Setting up Eclipse
-----------------------
-
-Eclipse users should install the UIMA Eclipse Plugins and UIMA Examples Project using the
-procedure described in Chapter 3 of the Apache UIMA Overview and Setup guide,
-which you can find online at http://uima.apache.org; click on Documentation ->
-HTML Online Version -> Overview and Setup -> 3. Eclipse IDE setup for UIMA.
-
-NOTE: The minimal version of Eclipse for UIMA-AS plugins is Mars (v.4.5.2).
-
-
-Since UIMA AS requires Java 8, you must be sure to set up your uimaj-examples Eclipse
-project to use a version 8 (or later) JRE, and you must set your compiler compliance level to 8.0. To do
-this go to Window->Preferences and navigate to the Java->Compiler page. Remember to
-run the base Eclipse using Java 8 (or later), as well.
-
-
-3. Getting Started
-==================
-
-3.1 Starting the ActiveMQ Broker
---------------------------------
-UIMA AS includes a partial distribution of Apache ActiveMQ to support core functionality of
-the broker. This includes a single broker support, network of brokers with fixed URLs, stomp, persistence,
-http, ssl, openwire, springframework integration, and jetty. If you need additional broker functionality you
-need to download and install a complete version of ActiveMQ from http://activemq.apache.org/download.html.
-
-
-UIMA AS services require an ActiveMQ broker to be available with which to create/register
-the service request queue. If no broker is available, start a new broker on the same machine
-the services will run on or another machine; this is done by first setting an env parameter
-ACTIVEMQ_BASE pointing at a writable directory, or simply by cd'ing to a writable directory,
-and running:
-
- startBroker.sh/bat
-
-The first time run this script will create a new directory $ACTIVEMQ_BASE/amq (or ./amq)
-and default configuration files will be copied there. The configuration files can then be
-customized to modify broker behavior for subsequent startups.
-
-Note: only one broker can be started at a time on the same machine with the same
- configuration file, or on different machines from the same writable directory.
-
-When the broker starts it will print a message such as:
-
- INFO TransportServerThreadSupport - Listening for connections at: tcp://yourHostname:61616
-
-Note this URL since you will need it to run services and clients.
-
-The tcp listening port must be exposed to any clients or services using the broker.
-To connect to a broker running behind a firewall using HTTP tunneling, see section 3.6 below.
-
-3.2 Deploying an Analysis Engine as a UIMA AS Asynchronous Service
-------------------------------------------------------------------
-
-a. Create a Deployment Descriptor.
- Examples can be found in the examples/deploy/as directory,
- and the syntax is documented in docs/d/uima_async_scaleout.pdf.
-
- Note: One of the things that the deployment descriptor may contain is a broker placeholder with
- this syntax: ${defaultBrokerURL}. The placeholder is replaced at runtime with an actual broker
- URL. The value for the placeholder comes from System properties. The brokerURL attribute of <inputQueue ...>
- element is optional. If not present, a default of tcp://localhost:61616 will be used.
-
- The examples assume the broker is listening on tcp://localhost:61616.
-
-b. Run the command:
-
- deployAsyncService.sh/cmd [testDD.xml] [-brokerURL url]
-
- The argument to the command is the deployment descriptor you created in step (a). An optional argument
- -brokerURL specifies a URL of the broker that the service will use to create connections to queues. This
- argument takes effect only if your deployment descriptor does not explicitly name the broker URL in the
- <inputQueue ...> xml element *or* the brokerURL attribute is set to a placeholder ${defaultBrokerURL}.
- Omitting brokerURL or using a placeholder is a way to keep your deployment descriptors portable. You don't
- need to edit your deployment descriptors when switching brokers.
-
- Note: If you use import by name in your deployment descriptor, UIMA AS searches the CLASSPATH
- as well as directories on UIMA_DATAPATH to resolve the import.
-
- Note: deployAsyncService.sh/cmd scripts launch UimaBootstrap main program which loads UIMA jars
- dynamically from UIMA_HOME/lib, UIMA_HOME/apache-activemq, and UIMA_HOME/apache-activemq/lib.
- directories. If you want to use a different
- version of ActiveMQ, set the ACTIVEMQ_HOME environment variable to the location of
- ActiveMQ you intend to use. When using different version of ActiveMQ ( older than version 5.4), start
- the broker using a startup script located in ACTIVEMQ_HOME/bin directory instead of
- UIMA_HOME/bin/startBroker.[cmd|sh] script provided in this release. This is due to the fact that the
- 5.4 branch of ActiveMQ xml schema has changed. The activemq_nojournal.xml provided in this release two
- optimizations: schedulerSupport=false to disable broker message scheduler, and producerFlowControl="false"
- to turn off producer flow control.
-
- Also, if you want to deploy your own annotator that is
- installed in a different directory than UIMA_HOME/lib, set the UIMA_CLASSPATH
- environment variable to point to one or more Classpath entries; these entries can either be
- directories of Java class files, Jar files, or directories of Jar files (in which case, all the
- Jars are added in an arbitrary order). Separate multiple entries using File.pathSeparator.
-
- Note: Both UIMA AS client and UIMA AS service by default add a time-to-live (TTL) to
- every request message. This enables expiration of messages that are not consumed.
- Currently, the UIMA AS client multiplies the Process Timeout value by 10 and uses
- this as TTL. The UIMA AS service sets TTL to the Timeout value multiplied by the number
- of outstanding requests. To disable TTL, add a system property -DNoTTL. A convenient
- way to set this parameter is by adding -DNoTTL to the env parameter UIMA_JVM_OPTS
- before running deployAsyncService and/or runRemoteAsyncAE.
-
-
-3.3 Calling a UIMA AS Asynchronous Service
-------------------------------------------
-
-To test a remote UIMA service you can use the script:
- runRemoteAsyncAE.sh/cmd brokerUrl endpoint
-
- This connects to a remote AE at specified brokerUrl and endpoint (which must match
- the inputQueue endpoint in the remote AE service's deployment descriptor).
-
- A subset of the optional arguments to runRemoteAsyncAE are:
- -c Specifies a CollectionReader descriptor. The client will obtain CASes from the
- CollectionReader and send them to the service for processing. If this option
- is omitted, one empty CAS will be sent to the service (useful for services
- containing a CAS Multiplier acting as a collection reader).
-
- -d Specifies a deployment descriptor. The specified service will be deployed before processing
- begins, and the service will be undeployed after processing completes.
- Multiple -d entries can be given.
-
- -o Specifies an Output Directory. All CASes received by the client's
- CallbackListener will be serialized to XMI in the specified OutputDir.
- If omitted, no XMI files will be output.
-
- The full set of arguments are documented if you type the command with no arguments.
-
-3.4 Quick Test of an async service
-----------------------------------
-
-Start two terminal windows, each with an environments setup as described in section 2.2.
-
- * In the first terminal window start the broker (as described in section 3.1),
- by running the commands:
- cd some-writable-directory
- startBroker.sh/bat
-
- * In the second terminal window, deploy a sample service and send it some CASes:
- cd $UIMA_HOME/examples/deploy/as
- runRemoteAsyncAE.sh/cmd tcp://localhost:61616 MeetingDetectorTaeQueue \
- -d Deploy_MeetingDetectorTAE.xml \
- -c $UIMA_HOME/examples/descriptors/collection_reader/FileSystemCollectionReader.xml
-
- If you get an UnsupportedClassVersionError, Java 8 is probably not being used.
- If the driver fails to find the input data, adjustExamplePaths was probably not run.
-
- To target specific service instance, use these steps:
- cd $UIMA_HOME/examples/deploy/as
- deployAsyncService.sh/cmd Deploy_MeetingDetectorTAE.xml
-
- Note this process PID. Assuming the process is launched on a machine with
- IP 1.1.1.1 and the PID is 2222, launch runRemoteAsyncAE as follows:
-
- runRemoteAsyncAE.sh/cmd tcp://localhost:61616 MeetingDetectorTaeQueue \
- -c $UIMA_HOME/examples/descriptors/collection_reader/FileSystemCollectionReader.xml
- -TargetServiceId 1.1.1.1:2222
-
- When the process completes you should see multiple lines of output that look like this:
-
- CAS received by service with selector: 1.1.1.1:2222
-
-3.5 Calling a UIMA AS Asynchronous Service from an Existing UIMA Application
-
-You can also call a UIMA AS Service from the DocumentAnalyzer or any other UIMA
-application using a new JMS client Service Descriptor
-(see section 1.7 in the UIMA Asynchronous Scaleout documentation).
-However, note that this is a synchronous interface, that is, it will process only
-one CAS at a time, so it will not take advantage of the scalability that UIMA AS
-provides. To process more than one CAS at a time, you can use the Asynchronous
-UIMA AS Client as described in section 3.3, or write your own application using the
-UIMA AS Client APIs.
-
-An example JMS client service descriptor is provided in
-
- examples/descriptors/as/MeetingDetectorAsyncAE.xml
-
-The JMS service makes use of the customResourceSpecifier capability in Apache UIMA.
-For more information on the customResourceSpecifier see the "Custom Resource Specifiers"
-section in the Apache UIMA Reference manual.
-
-3.6 Firewalls between clients and services
-------------------------------------------
-
-A service running behind a firewall can be accessed as long as its input queue
-is on a broker that is accessable. For example, the service can register with a
-public broker running outside the firewall. Alternatively the broker may be configured
-to tunnel over HTTP. For details see http://activemq.apache.org/configuring-transports.html
-
-The UIMA-AS ships with http support enabled. This is configured in broker configuration file found
-in $UIMA_HOME/as_config/activemq-nojournal.xml. By default, the broker listens for http
-based connections on port 8080. If you need to change the port, please modify broker
-configuration file by changing the following line:
-
- <transportConnector name="http" uri="http://0.0.0.0:8080"/>
-
-
-3.7 Monitoring a broker and its queues
---------------------------------------
-
-When the broker starts it will print a message such as:
- INFO ManagementContext - JMX consoles can connect to service:jmx:rmi:///jndi/rmi://localhost:1099/jmxrmi
-
-Connect a JMX console to this service with:
- $JAVA_HOME/bin/jconsole service:jmx:rmi:///jndi/rmi://localhost:1099/jmxrmi
-
-(Note: jconsole is available in Java SDK (not JRE) distributions from Sun)
-If your console is not on the same machine as the broker, replace localhost by
-the name of the broker's machine. The default ports for the broker (61616) and
-for the JMX server (1099) can be overridden in the broker configuration file
-created when the broker is first started. For more details see
-http://activemq.apache.org/jmx.html
-
-3.8 Monitoring UIMA AS service
-------------------------------
-
-UIMA AS service monitoring is available via JMX and jConsole. To enable this, please set the following
-before starting a service:
-
-set UIMA_JVM_OPTS=-Dcom.sun.management.jmxremote -Dcom.sun.management.jmxremote.port=<uniquePortNumber, e.g. 8009>
- -Dcom.sun.management.jmxremote.authenticate=false -Dcom.sun.management.jmxremote.ssl=false
-
-Connect a jConsole to this JMX service as described in 3.7 above using the appropriate port, e.g.
-
- $JAVA_HOME/bin/jconsole service:jmx:rmi:///jndi/rmi://localhost:8009/jmxrmi
-
-Under the MBeans tab, expand org.apache.uima in the left panel to view UIMA components enabled for JMX monitoring.
-
-NOTE:
-In case when opening an RMI port for JMX monitoring is not possible due to security concerns, you can disable
-JMX via optional argument -Duima.as.enable.jmx=false. With this setting, the UIMA-AS will start with no
-JMX support and an RMI port will not be opened.
-
-3.9 Stopping UIMA AS service
-----------------------------
-
-A service can be stopped from a command line or remotely using jConsole and JMX. When the service is
-launched it displays a prompt on stdout:
-
- Enter 'q' to quiesce and stop the service or 's' to stop it now:
-
-It reads stdin expecting either 'q' or 's', ignoring all other characters. When 'q' is typed, the
-service will quiesce and stop. As part of this, the service closes its input queue and waits until all CASes
-still "in-play" are finished. When the input CAS is returned the service stops. When 's' is typed the service
-closes its input queue and immediately releases all CASes being processed and stops.
-
-To stop UIMA AS process remotely or if the process runs in a background use jConsole and JMX. Using approach
-described in 3.8 above launch jConsole. Once the connection is created, in the left pane open:
-
-org.apache.uima
- ee.jms.service
- <Your Annotator Name> Uima EE Service
- Controller
- Operations
-
-Here you will find two buttons labeled:
- CompleteProcessingAndStop
- StopNow
-
-CompleteProcessingAndStop will initiate quiesce while StopNow will initiate a hard stop.
-
-4. Migration from CPM to UIMA-AS
-================================
-
-Migrating a collection processing engine from the CPM to UIMA-AS is straightforward.
-
-First, migrate the CPE descriptor to a standard UIMA aggregate descriptor:
-create a UIMA aggregate that includes all the components specified in the CPE descriptor.
-Transfer any parameter overrides in the CPE descriptor to the aggregate descriptor.
-Note that the aggreate descriptor must set <multipleDeploymentAllowed> to false
-to be consistent with collection reader and CAS consumer delegates.
-
-Second, test this aggregate descriptor by instantiating the aggregate and sending it a single CAS.
-The contents of the CAS are not important; its purpose is to start the collection reader delegate
-which will then create the actual CASes to be processed by the other aggregate components.
-The CAS Visual Debugger, CVD, is a useful tool for doing this test.
-
-Next, create a UIMA-AS deployment descriptor that specifies desired scaleout and error handling.
-Vinci services are still supported, although it is recommended to replace them with UIMA-AS
-services to enable more efficient load balancing and greater scaleout capability.
-
-An example of this kind of migration is embodied by the sample descriptors:
- Original:
- $UIMA_HOME/examples/descriptors/collection_processing_engine/MeetingFinderCPE_Integrated.xml
- Migrated:
- $UIMA_HOME/examples/deploy/as/MeetingFinderAggregate.xml
- $UIMA_HOME/examples/deploy/as/Deploy_MeetingFinder.xml
-
-
-5. Service Targeting (New Feature)
-==================================
-Service targeting allows an application client to send CASes to a specific instance of UIMA-AS service. This
-feature can be used to determine if a service is viable or not. When a service starts, it creates a new
-listener on its input queue which handles messages containing property 'TargetServiceId'. By default, the
-property value has a format <IP>:<PID>. If an incoming message contains the property with a value matching
-service <IP>:<PID>, the listener will dequeue the message and process a CAS contained therein. Optionally, the
-UIMA-AS service deployer may choose a different value for the 'TargetServiceId' property. To override the default
-include -DTargetServiceId=<value> on the service command line. The <value> may be an arbitrary string with
-no spaces.
-
-To target a specific service instance, an application client must use UIMA-AS client API.
-For async calls, use
-
-sendCAS(CAS cas, String serviceId)
-
-and for synchronous calls, use
-
-sendAndReceiveCAS(CAS aCAS, List<AnalysisEnginePerformanceMetrics> componentMetricsList, String serviceId)
-
-where serviceId is a unique service identifier as described above.
-
-6. Known problems/limitations with Release 2.10.3
-================================================
-
- 1. When connecting to an AMQ broker behind a firewall, avoid using the maxInactivityDuration=0
- decoration on the brokerURL (see: http://activemq.apache.org/configuring-wire-formats.html)
- as it turns off AMQ 'keep alive' messaging. Without these, a firewall may assume a connection
- has become stale and close its ports.
-
- 2. To monitor multiple UIMA AS services on the same machine, each must be assigned a unique
- JMX port (see section 3.8).
-
- 3. JCAS caching Enable/Disable not supported in the Deployment Editor GUI.
-
- 4. In cases where Analysis Engine deployed in UIMA AS service throws a user-defined exception, an
- application hosting UIMA AS client must include such exception class in its classpath. Otherwise,
- ClassNotFoundException is thrown in the UIMA AS client while deserializing a reply.
-
-For up-to-date information on UIMA-AS issues, see our issue tracker:
-https://issues.apache.org/jira/browse/UIMA-5385?filter=12317266&jql=project%20%3D%20UIMA%20AND%20component%20%3D%20%22Async%20Scaleout%22%20AND%20fixversion%3D2.10.2AS%20and%20status%3DClosed
-
-
-Crypto Notice
--------------
-
- This distribution includes cryptographic software. The country in
- which you currently reside may have restrictions on the import,
- possession, use, and/or re-export to another country, of
- encryption software. BEFORE using any encryption software, please
- check your country's laws, regulations and policies concerning the
- import, possession, or use, and re-export of encryption software, to
- see if this is permitted. See <http://www.wassenaar.org/> for more
- information.
-
- The U.S. Government Department of Commerce, Bureau of Industry and
- Security (BIS), has classified this software as Export Commodity
- Control Number (ECCN) 5D002.C.1, which includes information security
- software using or performing cryptographic functions with asymmetric
- algorithms. The form and manner of this Apache Software Foundation
- distribution makes it eligible for export under the License Exception
- ENC Technology Software Unrestricted (TSU) exception (see the BIS
- Export Administration Regulations, Section 740.13) for both object
- code and source code.
-
- The following provides more details on the included cryptographic
- software:
-
- This distribution includes portions of Apache ActiveMQ, which, in
- turn, is classified as being controlled under ECCN 5D002.
diff --git a/README.md b/README.md
new file mode 100644
index 00000000..7868a81b
--- /dev/null
+++ b/README.md
@@ -0,0 +1,469 @@
+Apache UIMA Asynchronous Scaleout (UIMA-AS)
+===========================================
+
+What is UIMA-AS?
+----------------
+
+UIMA Asynchronous Scaleout (AS) is an augmented version of Apache UIMA
+that additionally provides a set of capabilities for achieving flexible
+scaleout. It is a second generation design, replacing the CPM and Vinci
+Services. The CPM and Vinci are still available and are not being
+deprecated, but new designs are encouraged to use UIMA-AS for
+scalability, and current designs reaching limitations may want to move
+to UIMA-AS.
+
+UIMA-AS is integrated with the new flow controller architecture, and can
+be applied to both primitive and aggregate analysis engines. It fully
+supports CAS Multipliers.
+
+
+Building from the Source Distribution
+-------------------------------------
+
+We use Maven 3.3.+ for building; download this if needed,
+and set the environment variable `MAVEN_OPTS to -Xmx800m -XX:MaxPerSize-256m`.
+
+Then build from the directory containing this README by issuing the command
+
+ mvn clean install.
+
+This builds everything except the ...source-release.zip file. If you want that,
+change the command to
+
+ mvn clean install -Papache-release
+
+Look for the result in the two artifacts:
+
+ target/uima-as-[version]-source-release.zip (if run with -Papache-release) and
+ target/uima-as-[version]-bin.zip (or ...tar.gz)
+
+If your maven build fails with strange errors try running maven with an update flag
+like this:
+
+ mvn -U clean install
+
+Note that a build with -U option takes much longer to finish.
+
+For more details, please see http://uima.apache.org/building-uima.html
+
+
+It includes the base UIMA binary distribution which it depends on.
+
+UIMA-AS components, in addition to those that come with base UIMA include:
+
+#### Shell scripts
+
+* `bin/startBroker.sh/bat`: starts the ActiveMQ broker, which must be running before
+ UIMA AS services can be deployed.
+* `bin/deployAsyncService.sh/bat`: deploys an AnalysisEngine as a UIMA-AS
+ service. Takes one or more UIMA-AS Deployment Descriptors as arguments.
+* `bin/runRemoteAsyncAE.sh/bat`: Calls a UIMA-AS service. Takes arguments
+ specifying the location of the service, and an optional `CollectionReader`
+ descriptor file used to obtain the CASes to be processed by the service.
+
+#### Documentation
+
+* `docs/d/uima_async_scaleout.pdf`: UIMA-AS documentation, including the
+ specification for the deployment descriptor file syntax.
+
+#### Examples
+
+* `examples/deploy/as/...` (Sample Deployment Descriptors)
+ * `Deploy_RoomNumberAnnotator.xml`: Deploys Room Number Annotator Primitive AE
+ * `Deploy_MeetingDetectorTAE.xml`: Deploys Meeting Detector Aggregate AE with all
+ delegates in the same JVM.
+ * `Deploy_MeetingDetectorTAE_Whiteboard.xml`: Deploys Meeting Detector Aggregate
+ AE using the whiteboard Flow Controller.
+ * `Deploy_MeetingDetectorTAE_RemoteRoomNumber.xml`: Deploys Meeting Detector
+ Aggregate AE that uses remotely deployed RoomNumberAnnotator.
+ * `Deploy_MeetingDetectorTAE_3MeetingAnnotator.xml`: Deploys Meeting Detector
+ Aggregate AE with three instances of the MeetingAnnotator component.
+ * `Deploy_MeetingDetectorTAE_Sync_3Instances.xml`: Deploys 3 instances of the
+ Meeting Detector as a Synchronous Aggregate (meaning the delegate AEs do not
+ each get their own input queue).
+ * `Deploy_MeetingAnnotator.xml`: Deploys C++ Meeting Annotator. Note: requires
+ installation of uimacpp SDK into `$UIMA_HOME`.
+ * `MeetingFinderAggregate.xml`: Aggregate descriptor that use the same components
+ as the CPE examples MeetingFinderCPE* in base UIMA.
+ * `Deploy_MeetingFinder.xml`: Deploys MeetingFinderAggregate illustrating
+ scalability and error handling similar to the CPM examples; see the notes on migration below.
+
+#### Descriptors:
+
+* `descriptors/as/...` (Other Sample Descriptors for use with UIMA AS)
+ * `MeetingDetectorAsyncAE.xml:` Specifier that can be used to call a UIMA AS
+ Service from an existing UIMA application; see below.
+
+
+Installation and Setup
+----------------------
+
+### Supported Platforms
+
+Apache UIMA-AS requires Java version 8 or later; it has been tested with Sun/Oracle Java 8 and IBM 8.
+
+Running the Eclipse plugin tooling for UIMA requires you start Eclipse using a Java 8 or later, as well.
+
+The supported platforms are: Windows, Linux, and Mac OS X. Other platforms and Java (8+)
+implementations should work, but have not been significantly tested.
+
+
+### Environment Variables
+
+After you have unpacked the UIMA AS distribution, you must perform the following
+environment variable settings (the same as for normal Apache UIMA setup):
+
+* Set `JAVA_HOME` to the directory of your JRE installation you would like to use for UIMA.
+* Set `UIMA_HOME` to the apache-uima-as directory of your unpacked Apache UIMA distribution
+* Append `UIMA_HOME/bin` to your `PATH`
+
+NOTE: The Mac OS X operating system has special procedures for setting up global
+ environment variables; see http://developer.apple.com/qa/qa2001/qa1067.html for
+ how to do this.
+
+
+### Running the Setup Script
+
+You must run the script `UIMA_HOME/bin/adjustExamplePaths.bat` (or `.sh`). This
+updates paths in the examples based on the actual UIMA_HOME directory path.
+
+
+### Setting up Eclipse
+
+Eclipse users should install the UIMA Eclipse Plugins and UIMA Examples Project
+using the procedure described in Chapter 3 of the Apache UIMA Overview and Setup
+guide, which you can find online at http://uima.apache.org; click on Documentation
+-> HTML Online Version -> Overview and Setup -> 3. Eclipse IDE setup for UIMA.
+
+NOTE: The minimal version of Eclipse for UIMA-AS plugins is Mars (v.4.5.2).
+
+Since UIMA AS requires Java 8, you must be sure to set up your `uimaj-examples`
+Eclipse project to use a version 8 (or later) JRE, and you must set your compiler
+compliance level to 8.0. To do this go to **Window->Preferences** and navigate to the Java->Compiler page. Remember to run the base Eclipse using Java 8 (or later), as well.
+
+
+Getting Started
+---------------
+
+### Starting the ActiveMQ Broker
+
+UIMA AS includes a partial distribution of Apache ActiveMQ to support core
+functionality of the broker. This includes a single broker support, network of
+brokers with fixed URLs, stomp, persistence, http, ssl, openwire, springframework
+integration, and jetty. If you need additional broker functionality you need to
+download and install a complete version of ActiveMQ from
+http://activemq.apache.org/download.html.
+
+UIMA AS services require an ActiveMQ broker to be available with which to
+create/register the service request queue. If no broker is available, start a new
+broker on the same machine the services will run on or another machine; this is
+done by first setting an env parameter `ACTIVEMQ_BASE` pointing at a writable
+directory, or simply by cd'ing to a writable directory, and running:
+
+ startBroker.sh/bat
+
+The first time run this script will create a new directory `$ACTIVEMQ_BASE/amq` (or
+`./amq`) and default configuration files will be copied there. The configuration
+files can then be customized to modify broker behavior for subsequent startups.
+
+NOTE: only one broker can be started at a time on the same machine with the same
+ configuration file, or on different machines from the same writable directory.
+
+When the broker starts it will print a message such as:
+
+ INFO TransportServerThreadSupport - Listening for connections at: tcp://yourHostname:61616
+
+Note this URL since you will need it to run services and clients.
+
+The tcp listening port must be exposed to any clients or services using the broker.
+To connect to a broker running behind a firewall using HTTP tunneling, see below.
+
+### Deploying an Analysis Engine as a UIMA AS Asynchronous Service
+
+* Create a Deployment Descriptor.
+ Examples can be found in the `examples/deploy/as` directory,
+ and the syntax is documented in `docs/d/uima_async_scaleout.pdf`.
+
+ NOTE: One of the things that the deployment descriptor may contain is a broker
+ placeholder with this syntax: `${defaultBrokerURL}`. The placeholder is replaced
+ at runtime with an actual broker URL. The value for the placeholder comes from
+ System properties. The `brokerURL` attribute of `<inputQueue ...>` element is
+ optional. If not present, a default of `tcp://localhost:61616` will be used.
+
+ The examples assume the broker is listening on `tcp://localhost:61616`.
+
+* Run the command:
+
+ deployAsyncService.sh/cmd [testDD.xml] [-brokerURL url]
+
+ The argument to the command is the deployment descriptor you created in step (a).
+ An optional argument `-brokerURL` specifies a URL of the broker that the service
+ will use to create connections to queues. This argument takes effect only if your
+ deployment descriptor does not explicitly name the broker URL in the
+ `<inputQueue ...>` xml element *or* the `brokerURL` attribute is set to a
+ placeholder `${defaultBrokerURL}`.
+ Omitting brokerURL or using a placeholder is a way to keep your deployment
+ descriptors portable. You don't need to edit your deployment descriptors when
+ switching brokers.
+
+ NOTE: If you use import by name in your deployment descriptor, UIMA AS searches
+ the `CLASSPATH` as well as directories on `UIMA_DATAPATH` to resolve the import.
+
+ NOTE: `deployAsyncService.sh/cmd` scripts launch `UimaBootstrap` main program w
+ which loads UIMA jars dynamically from `UIMA_HOME/lib`,
+ `UIMA_HOME/apache-activemq`, and `UIMA_HOME/apache-activemq/lib` directories. If
+ you want to use a different version of ActiveMQ, set the `ACTIVEMQ_HOME`
+ environment variable to the location of ActiveMQ you intend to use. When using
+ different version of ActiveMQ ( older than version 5.4), start
+ the broker using a startup script located in `ACTIVEMQ_HOME/bin` directory
+ instead of `UIMA_HOME/bin/startBroker.[cmd|sh]` script provided in this release.
+ This is due to the fact that the 5.4 branch of ActiveMQ xml schema has changed. The `activemq_nojournal.xml` provided in this release two optimizations: `schedulerSupport=false` to disable broker message scheduler, and `producerFlowControl="false"` to turn off producer flow control.
+
+ Also, if you want to deploy your own annotator that is installed in a different
+ directory than `UIMA_HOME/lib`, set the `UIMA_CLASSPATH` environment variable to
+ point to one or more Classpath entries; these entries can either be
+ directories of Java class files, Jar files, or directories of Jar files (in which
+ case, all the Jars are added in an arbitrary order). Separate multiple entries
+ using `File.pathSeparator`.
+
+ NOTE: Both UIMA AS client and UIMA AS service by default add a time-to-live (TTL)
+ to every request message. This enables expiration of messages that are not
+ consumed. Currently, the UIMA AS client multiplies the Process Timeout value by
+ 10 and uses this as TTL. The UIMA AS service sets TTL to the Timeout value
+ multiplied by the number of outstanding requests. To disable TTL, add a system
+ property `-DNoTTL`. A convenient way to set this parameter is by adding `-DNoTTL`
+ to the env parameter `UIMA_JVM_OPTS` before running deployAsyncService and/or `runRemoteAsyncAE`.
+
+
+### Calling a UIMA AS Asynchronous Service
+
+To test a remote UIMA service you can use the script:
+
+ runRemoteAsyncAE.sh/cmd brokerUrl endpoint
+
+This connects to a remote AE at specified brokerUrl and endpoint (which must match
+the inputQueue endpoint in the remote AE service's deployment descriptor).
+
+A subset of the optional arguments to runRemoteAsyncAE are:
+* `-c`: Specifies a CollectionReader descriptor. The client will obtain CASes from
+ the `CollectionReader` and send them to the service for processing. If this
+ option is omitted, one empty CAS will be sent to the service (useful for services
+ containing a CAS Multiplier acting as a collection reader).
+
+* `-d`: Specifies a deployment descriptor. The specified service will be deployed
+ before processing begins, and the service will be undeployed after processing
+ completes. Multiple `-d` entries can be given.
+
+* `-o`: Specifies an Output Directory. All CASes received by the client's
+ `CallbackListener` will be serialized to XMI in the specified `OutputDir`.
+ If omitted, no XMI files will be output.
+
+The full set of arguments are documented if you type the command with no arguments.
+
+
+### Quick Test of an async service
+
+Start two terminal windows, each with an environments setup as described earlier
+
+* In the first terminal window start the broker, by running the commands:
+
+ cd some-writable-directory
+ startBroker.sh/bat
+
+* In the second terminal window, deploy a sample service and send it some CASes:
+
+ cd $UIMA_HOME/examples/deploy/as
+ runRemoteAsyncAE.sh/cmd tcp://localhost:61616 MeetingDetectorTaeQueue \
+ -d Deploy_MeetingDetectorTAE.xml \
+ -c $UIMA_HOME/examples/descriptors/collection_reader/FileSystemCollectionReader.xml
+
+ If you get an `UnsupportedClassVersionError`, Java 8 is probably not being used.
+ If the driver fails to find the input data, adjustExamplePaths was probably not run.
+
+ To target specific service instance, use these steps:
+
+ cd $UIMA_HOME/examples/deploy/as
+ deployAsyncService.sh/cmd Deploy_MeetingDetectorTAE.xml
+
+ Note this process PID. Assuming the process is launched on a machine with
+ IP `1.1.1.1` and the PID is `2222`, launch runRemoteAsyncAE as follows:
+
+ runRemoteAsyncAE.sh/cmd tcp://localhost:61616 MeetingDetectorTaeQueue \
+ -c $UIMA_HOME/examples/descriptors/collection_reader/FileSystemCollectionReader.xml
+ -TargetServiceId 1.1.1.1:2222
+
+ When the process completes you should see multiple lines of output that look like this:
+
+ CAS received by service with selector: 1.1.1.1:2222
+
+
+### Calling a UIMA AS Asynchronous Service from an Existing UIMA Application
+
+You can also call a UIMA AS Service from the `DocumentAnalyzer` or any other UIMA
+application using a new JMS client Service Descriptor
+(see section 1.7 in the UIMA Asynchronous Scaleout documentation).
+However, note that this is a synchronous interface, that is, it will process only
+one CAS at a time, so it will not take advantage of the scalability that UIMA AS
+provides. To process more than one CAS at a time, you can use the Asynchronous
+UIMA AS Client, or write your own application using the UIMA AS Client APIs.
+
+An example JMS client service descriptor is provided in
+
+ examples/descriptors/as/MeetingDetectorAsyncAE.xml
+
+The JMS service makes use of the customResourceSpecifier capability in Apache UIMA.
+For more information on the customResourceSpecifier see the "Custom Resource
+Specifiers" section in the Apache UIMA Reference manual.
+
+
+### Firewalls between clients and services
+
+A service running behind a firewall can be accessed as long as its input queue
+is on a broker that is accessable. For example, the service can register with a
+public broker running outside the firewall. Alternatively the broker may be
+configured to tunnel over HTTP. For details see
+http://activemq.apache.org/configuring-transports.html
+
+The UIMA-AS ships with http support enabled. This is configured in broker configuration file found in `$UIMA_HOME/as_config/activemq-nojournal.xml`. By
+default, the broker listens for http based connections on port 8080. If you need to
+change the port, please modify broker configuration file by changing the following
+line:
+
+ <transportConnector name="http" uri="http://0.0.0.0:8080"/>
+
+
+### Monitoring a broker and its queues
+
+When the broker starts it will print a message such as:
+
+ INFO ManagementContext - JMX consoles can connect to service:jmx:rmi:///jndi/rmi://localhost:1099/jmxrmi
+
+Connect a JMX console to this service with:
+
+ $JAVA_HOME/bin/jconsole service:jmx:rmi:///jndi/rmi://localhost:1099/jmxrmi
+
+NOTE: jconsole is available in Java SDK (not JRE) distributions from Sun
+
+If your console is not on the same machine as the broker, replace localhost by
+the name of the broker's machine. The default ports for the broker (61616) and
+for the JMX server (1099) can be overridden in the broker configuration file
+created when the broker is first started. For more details see
+http://activemq.apache.org/jmx.html
+
+
+### Monitoring UIMA AS service
+
+UIMA AS service monitoring is available via JMX and jConsole. To enable this,
+please set the following before starting a service:
+
+ set UIMA_JVM_OPTS=-Dcom.sun.management.jmxremote -Dcom.sun.management.jmxremote.port=<uniquePortNumber, e.g. 8009>
+ -Dcom.sun.management.jmxremote.authenticate=false -Dcom.sun.management.jmxremote.ssl=false
+
+Connect a jConsole to this JMX service as described in 3.7 above using the appropriate port, e.g.
+
+ $JAVA_HOME/bin/jconsole service:jmx:rmi:///jndi/rmi://localhost:8009/jmxrmi
+
+Under the MBeans tab, expand org.apache.uima in the left panel to view UIMA components enabled for JMX monitoring.
+
+NOTE: In case when opening an RMI port for JMX monitoring is not possible due to
+security concerns, you can disable JMX via optional argument
+`-Duima.as.enable.jmx=false`. With this setting, the UIMA-AS will start with no
+JMX support and an RMI port will not be opened.
+
+
+### Stopping UIMA AS service
+
+A service can be stopped from a command line or remotely using jConsole and JMX.
+When the service is launched it displays a prompt on stdout:
+
+ Enter 'q' to quiesce and stop the service or 's' to stop it now:
+
+It reads stdin expecting either `q` or `s`, ignoring all other characters. When `q`
+is typed, the service will quiesce and stop. As part of this, the service closes
+its input queue and waits until all CASes still "in-play" are finished. When the
+input CAS is returned the service stops. When 's' is typed the service
+closes its input queue and immediately releases all CASes being processed and stops.
+
+To stop UIMA AS process remotely or if the process runs in a background use
+jConsole and JMX. Using approach described in 3.8 above launch jConsole. Once the
+connection is created, in the left pane open:
+
+ org.apache.uima
+ ee.jms.service
+ <Your Annotator Name> Uima EE Service
+ Controller
+ Operations
+
+Here you will find two buttons labeled:
+
+ CompleteProcessingAndStop
+ StopNow
+
+CompleteProcessingAndStop will initiate quiesce while StopNow will initiate a hard stop.
+
+### Migration from CPM to UIMA-AS
+
+Migrating a collection processing engine from the CPM to UIMA-AS is straightforward.
+
+First, migrate the CPE descriptor to a standard UIMA aggregate descriptor:
+create a UIMA aggregate that includes all the components specified in the CPE
+descriptor. Transfer any parameter overrides in the CPE descriptor to the aggregate
+descriptor. Note that the aggreate descriptor must set
+`<multipleDeploymentAllowed>` to `false` to be consistent with collection reader
+and CAS consumer delegates.
+
+Second, test this aggregate descriptor by instantiating the aggregate and sending
+it a single CAS. The contents of the CAS are not important; its purpose is to start
+the collection reader delegate which will then create the actual CASes to be
+processed by the other aggregate components. The CAS Visual Debugger, CVD, is a
+useful tool for doing this test.
+
+Next, create a UIMA-AS deployment descriptor that specifies desired scaleout and error handling. Vinci services are still supported, although it is recommended to replace them with UIMA-AS services to enable more efficient load balancing and greater scaleout capability.
+
+An example of this kind of migration is embodied by the sample descriptors:
+
+ Original:
+ $UIMA_HOME/examples/descriptors/collection_processing_engine/MeetingFinderCPE_Integrated.xml
+ Migrated:
+ $UIMA_HOME/examples/deploy/as/MeetingFinderAggregate.xml
+ $UIMA_HOME/examples/deploy/as/Deploy_MeetingFinder.xml
+
+
+### Service Targeting (New Feature)
+
+Service targeting allows an application client to send CASes to a specific instance
+of UIMA-AS service. This feature can be used to determine if a service is viable or
+not. When a service starts, it creates a new listener on its input queue which
+handles messages containing property `TargetServiceId`. By default, the
+property value has a format `<IP>:<PID>`. If an incoming message contains the
+property with a value matching service `<IP>:<PID>`, the listener will dequeue the
+message and process a CAS contained therein. Optionally, the UIMA-AS service
+deployer may choose a different value for the `TargetServiceId` property. To
+override the default include `-DTargetServiceId=<value>` on the service command
+line. The `<value>` may be an arbitrary string with no spaces.
+
+To target a specific service instance, an application client must use UIMA-AS client API. For async calls, use
+
+ sendCAS(CAS cas, String serviceId)
+
+and for synchronous calls, use
+
+ sendAndReceiveCAS(CAS aCAS, List<AnalysisEnginePerformanceMetrics> componentMetricsList, String serviceId)
+
+where `serviceId` is a unique service identifier as described above.
+
+
+How to Get Involved
+-------------------
+
+The Apache UIMA project really needs and appreciates any contributions,
+including documentation help, source code and feedback. If you are
+interested in contributing, please visit
+<http://uima.apache.org/get-involved.html>.
+
+
+How to Report Issues
+--------------------
+
+The Apache UIMA project uses JIRA for issue tracking. Please report any
+issues you find at <http://issues.apache.org/jira/browse/uima>
diff --git a/RELEASE_NOTES.html b/RELEASE_NOTES.html
deleted file mode 100644
index 1f66307f..00000000
--- a/RELEASE_NOTES.html
+++ /dev/null
@@ -1,81 +0,0 @@
-<html>
- <!--
- ***************************************************************
- * 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.
- ***************************************************************
- -->
-<head>
- <title>Apache UIMA Asynchronous Scaleout v2.10.3 Release Notes</title>
-</head>
-<body>
-<h1>Apache UIMA-AS (Unstructured Information Management Architecture - Asynchronous Scaleout) v2.10.3 Release Notes</h1>
-
-<h2>Contents</h2>
-<p>
-<a href="#what.is.uima-as">1. What is UIMA-AS?</a><br/>
-<a href="#major.changes">2. Major Changes in this Release</a><br/>
-<a href="#get.involved">3. How to Get Involved</a><br/>
-<a href="#report.issues">4. How to Report Issues</a><br/>
-<a href="#list.issues">5. List of JIRA Issues Fixed in this Release</a>
-</p>
-
-<h2><a name="what.is.uima-as">1. What is UIMA-AS?</a></h2>
-
- <p>
- UIMA Asynchronous Scaleout (AS) is an augmented version of Apache UIMA that
- additionally provides a set of capabilities
-for achieving flexible scaleout. It is a second generation design, replacing the
-CPM and Vinci Services. The CPM and Vinci are still available and are not being deprecated,
-but new designs are encouraged to use UIMA-AS for scalability, and current designs
-reaching limitations may want to move to UIMA-AS.
-
- </p>
- <p>
- UIMA-AS is integrated with the new flow controller architecture, and can be applied to
-both primitive and aggregate analysis engines. It fully supports CAS Multipliers.
- </p>
-
-<h2><a name="major.changes">2. Major Changes in this Release</a></h2>
-<p>
-Please see the <a href="README">README</a> for this information.
-</p>
-
-
-<h2><a name="get.involved">3. How to Get Involved</a></h2>
-<p>
-The Apache UIMA project really needs and appreciates any contributions,
-including documentation help, source code and feedback. If you are interested
-in contributing, please visit
-<a href="http://uima.apache.org/get-involved.html">
- http://uima.apache.org/get-involved.html</a>.
-</p>
-
-<h2><a name="report.issues">4. How to Report Issues</a></h2>
-<p>
-The Apache UIMA project uses JIRA for issue tracking. Please report any
-issues you find at
-<a href="http://issues.apache.org/jira/browse/uima">http://issues.apache.org/jira/browse/uima</a>
-</p>
-
-<h2><a name="list.issues">5. List of JIRA Issues Fixed in this Release</a></h2>
-
-Click <a href="issuesFixed/jira-report.html">issuesFixed/jira-report.hmtl</a> for the list of
-issues fixed in this release.
-
-</body>
-</html>
diff --git a/RELEASE_NOTES.md b/RELEASE_NOTES.md
new file mode 100644
index 00000000..20e74dda
--- /dev/null
+++ b/RELEASE_NOTES.md
@@ -0,0 +1,75 @@
+Apache UIMA Asynchronous Scaleout (UIMA-AS) Version 2.10.3
+==========================================================
+
+What's New in 2.10.3
+--------------------
+
+- Modified client code to assign unique ClientID to broker connection
+- Fixed ClassCastException when async aggregate initializes delegate with JMS Service Descriptor
+- Fixed broken classpath and logging for UIMA-AS run configurations
+
+Click [issuesFixed/jira-report.hmtl](issuesFixed/jira-report.html) for
+the list of issues fixed in this release.
+
+
+Contents of Apache UIMA-AS binary distribution
+----------------------------------------------
+
+The Apache UIMA-AS binary distribution includes
+
+- Apache UIMA Java SDK version 2.10.2
+- Apache UIMA Asynchronous Scaleout extensions
+- Saxon
+- Apache ActiveMQ version 5.15.2
+- Spring Framework version 4.3.9
+- XMLBeans
+
+
+Known problems/limitations with Release 2.10.3
+----------------------------------------------
+
+* When connecting to an AMQ broker behind a firewall, avoid using the
+ `maxInactivityDuration=0` decoration on the brokerURL
+ (see: http://activemq.apache.org/configuring-wire-formats.html)
+ as it turns off AMQ 'keep alive' messaging. Without these, a firewall may assume
+ a connection has become stale and close its ports.
+* To monitor multiple UIMA AS services on the same machine, each must be assigned a
+ unique JMX port (see section 3.8).
+* JCAS caching Enable/Disable not supported in the Deployment Editor GUI.
+* In cases where Analysis Engine deployed in UIMA AS service throws a user-defined
+ exception, an application hosting UIMA AS client must include such exception
+ class in its classpath. Otherwise, ClassNotFoundException is thrown in the UIMA
+ AS client while deserializing a reply.
+
+For up-to-date information on UIMA-AS issues, see our issue tracker:
+https://issues.apache.org/jira/browse/UIMA-5385?filter=12317266&jql=project%20%3D%20UIMA%20AND%20component%20%3D%20%22Async%20Scaleout%22%20AND%20fixversion%3D2.10.2AS%20and%20status%3DClosed
+
+
+Crypto Notice
+-------------
+
+This distribution includes cryptographic software. The country in
+which you currently reside may have restrictions on the import,
+possession, use, and/or re-export to another country, of
+encryption software. BEFORE using any encryption software, please
+check your country's laws, regulations and policies concerning the
+import, possession, or use, and re-export of encryption software, to
+see if this is permitted. See <http://www.wassenaar.org/> for more
+information.
+
+The U.S. Government Department of Commerce, Bureau of Industry and
+Security (BIS), has classified this software as Export Commodity
+Control Number (ECCN) 5D002.C.1, which includes information security
+software using or performing cryptographic functions with asymmetric
+algorithms. The form and manner of this Apache Software Foundation
+distribution makes it eligible for export under the License Exception
+ENC Technology Software Unrestricted (TSU) exception (see the BIS
+Export Administration Regulations, Section 740.13) for both object
+code and source code.
+
+The following provides more details on the included cryptographic
+software:
+
+This distribution includes portions of Apache ActiveMQ, which, in
+turn, is classified as being controlled under ECCN 5D002.
+