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:42 UTC
[uima-async-scaleout] branch no-jira-readme-to-markdown created (now 5d01a85c)
This is an automated email from the ASF dual-hosted git repository.
rec pushed a change to branch no-jira-readme-to-markdown
in repository https://gitbox.apache.org/repos/asf/uima-async-scaleout.git
at 5d01a85c [NO JIRA] Convert readme and release notes to markdown - and move version-specific stuff to release notes and general stuff to the README
This branch includes the following new commits:
new 5d01a85c [NO JIRA] Convert readme and release notes to markdown - and move version-specific stuff to release notes and general stuff to the README
The 1 revisions listed above as "new" are entirely new to this
repository and will be described in separate emails. The revisions
listed as "add" were already present in the repository and have only
been added to this reference.
[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
Posted by re...@apache.org.
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.
+