Author: schor Date: Wed Oct 30 20:27:55 2013 New Revision: 1537283 URL: http://svn.apache.org/r1537283 Log: no Jira - add comments and a readme.html describing a bit how the test case scaffolding works for uima-as testing
Added: uima/uima-as/trunk/uimaj-as-activemq/src/test/java/org/apache/uima/ee/test/utils/readme.html Modified: uima/uima-as/trunk/uimaj-as-activemq/src/test/java/org/apache/uima/ee/test/utils/ActiveMQSupport.java uima/uima-as/trunk/uimaj-as-activemq/src/test/java/org/apache/uima/ee/test/utils/BaseTestSupport.java Modified: uima/uima-as/trunk/uimaj-as-activemq/src/test/java/org/apache/uima/ee/test/utils/ActiveMQSupport.java URL: http://svn.apache.org/viewvc/uima/uima-as/trunk/uimaj-as-activemq/src/test/java/org/apache/uima/ee/test/utils/ActiveMQSupport.java?rev=1537283&r1=1537282&r2=1537283&view=diff ============================================================================== --- uima/uima-as/trunk/uimaj-as-activemq/src/test/java/org/apache/uima/ee/test/utils/ActiveMQSupport.java (original) +++ uima/uima-as/trunk/uimaj-as-activemq/src/test/java/org/apache/uima/ee/test/utils/ActiveMQSupport.java Wed Oct 30 20:27:55 2013 @@ -58,6 +58,9 @@ public class ActiveMQSupport extends Tes protected static BrokerService broker; + /** + * Is set to uri of started broker for the TCP connection + */ protected String uri = null; protected static ThreadGroup brokerThreadGroup = null; @@ -81,7 +84,7 @@ public class ActiveMQSupport extends Tes protected synchronized void setUp() throws Exception { super.setUp(); - broker = createBroker(); + broker = createBroker(); // sets uri broker.setUseJmx(false); broker.start(); broker.setMasterConnectorURI(uri); @@ -98,6 +101,7 @@ public class ActiveMQSupport extends Tes // error handler action=terminate. System.setProperty("dontKill",""); } + protected void cleanBroker( BrokerService targetBroker) throws Exception { // Remove messages from all queues targetBroker.deleteAllMessages(); @@ -124,6 +128,7 @@ public class ActiveMQSupport extends Tes protected String addHttpConnector(int aDefaultPort) throws Exception { return addHttpConnector(broker, aDefaultPort); } + protected String addHttpConnector(BrokerService aBroker, int aDefaultPort) throws Exception { boolean found = false; while( !found ) { @@ -153,6 +158,7 @@ public class ActiveMQSupport extends Tes } throw new BrokerConnectionException("Unable to acquire Open Port for HTTPConnector"); } + protected String getHttpURI() throws Exception { while ( httpConnector == null ) { synchronized(this) { @@ -161,6 +167,7 @@ public class ActiveMQSupport extends Tes } return httpConnector.getConnectUri().toString(); } + protected void removeQueue(String aQueueName) throws Exception { httpConnector.stop(); } Modified: uima/uima-as/trunk/uimaj-as-activemq/src/test/java/org/apache/uima/ee/test/utils/BaseTestSupport.java URL: http://svn.apache.org/viewvc/uima/uima-as/trunk/uimaj-as-activemq/src/test/java/org/apache/uima/ee/test/utils/BaseTestSupport.java?rev=1537283&r1=1537282&r2=1537283&view=diff ============================================================================== --- uima/uima-as/trunk/uimaj-as-activemq/src/test/java/org/apache/uima/ee/test/utils/BaseTestSupport.java (original) +++ uima/uima-as/trunk/uimaj-as-activemq/src/test/java/org/apache/uima/ee/test/utils/BaseTestSupport.java Wed Oct 30 20:27:55 2013 @@ -148,6 +148,11 @@ public abstract class BaseTestSupport ex exceptionsToIgnore.add(anExceptionToIgnore); } + /** + * Test if an exception is in the ignore list + * @param anException + * @return true if exception is ignored, or arg is null + */ protected boolean ignoreException(Class<?> anException) { if (anException == null) { return true; @@ -396,6 +401,7 @@ public abstract class BaseTestSupport ex /** * Initializes a given instance of the Uima EE client and executes a test. It uses synchronization * to enforce correct sequence of calls and setups expected result. + * It sends "howMany" CASes all at once to the service. * * @param appCtx * @param aUimaEeEngine @@ -507,6 +513,7 @@ public abstract class BaseTestSupport ex /** * Initializes a given instance of the Uima EE client and executes a test. It uses synchronization * to enforce correct sequence of calls and setups expected result. + * It sends "howMany" CASes, one at a time, to the service, waiting after each one until it is completely done. * * @param appCtx * @param aUimaEeEngine Added: uima/uima-as/trunk/uimaj-as-activemq/src/test/java/org/apache/uima/ee/test/utils/readme.html URL: http://svn.apache.org/viewvc/uima/uima-as/trunk/uimaj-as-activemq/src/test/java/org/apache/uima/ee/test/utils/readme.html?rev=1537283&view=auto ============================================================================== --- uima/uima-as/trunk/uimaj-as-activemq/src/test/java/org/apache/uima/ee/test/utils/readme.html (added) +++ uima/uima-as/trunk/uimaj-as-activemq/src/test/java/org/apache/uima/ee/test/utils/readme.html Wed Oct 30 20:27:55 2013 @@ -0,0 +1,219 @@ + <!DOCTYPE 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. + *************************************************************** + --> + + <html> + <head> + <style> + mthd {font-weight: bold; font-family: monospace;} + fld {margin-left: 2em; display: block} + actn {margin-left: 2em; display: block} + </style> + </head> + <body> + <h1>UIMA-AS Testing Utilities</h1> + <h4>A brief guide to the utilities for helping +to construct uima-as test cases</h4> + +<p>Last updated: October, 2013</p> +<p>Test cases run lots of asynchronous parts. The main flow is to have a test case set things up, and then +set up 1 or more monitor threads that will await various latch countdowns (EXCEPTION, CPC, PROCESS). +The monitor threads are "joined" back in the main thread. There's an extra semiphore that is used to delay +sending the first CAS until all monitor threads have started up. +</p> + +<p>CASes in the system are assigned Cas Ref Ids, which are UUIDs.</p> + +<p>There are 2 support / utility classes, with this inheritance:<br/> +<code style="margin-left:2em">BaseTestSupport -> ActiveMQSupport -> TestCase</code></p> + +<h2>ActiveMQSupport</h2> +<h3>Starting / stopping broker(s)</h3> +<ul> +<li> +<p><mthd>setup()</mthd> creates and starts <code>broker</code> +<actn>creates, starts broker, addHttpConnector(port = 18888)</actn> +<actn>Sets system properties: +<pre> + DefaultBrokerUrl = broker:()/localhost?persistent=false + DefaultHttpBrokerUrl = http://localhost:[portNumber] +</pre></actn> +</p> +</li> + +<li> +<p><mthd>teardown</mthd> clears two System properties and stops <code>broker</code> +<fld>clear System properties <code>activemq.broker.jmx.domain, BrokerURL</code></fld> +</p> +</li> + +<li> +<p><mthd>cleanBroker(BrokerService broker)</mthd> sometimes done before stopping +<actn>deleteAllMessages - removes messages from all queues</actn> +<actn>goes thru all known Client connections and "stop()"s them</actn> +<actn>goes thru all non-topic destinations and removes them</actn> +<pre> + Typical use: + stop-uima-client; + cleanBroker(broker2); + broker2.stop() + broker2.waitUntilStopped(); +</pre> +</p> +</li> + +<li> +<p><mthd>stopBroker()</mthd> stops main <code>broker</code> +<fld><code>broker, tcpConnector</code></fld> +<actn>stop <code>tcpConnector</code>, removeConnector from broker, removeHttpConnector, deleteAllMessages, stop broker, waitUtilStopped</actn> +</p> +</li> +</ul> + +<h3>BrokerConnectors</h3> +<ul> +<li> +<p><mthd>addHttpConnector( [broker], port-number)</mthd> returns Uri String +<fld>set-field <code>TransportConnector httpConnector</code></fld> +<actn>Iterates with increasing port-number in case port in use</actn> +</p> +</li><li> + +<p><mthd>getHttpURI()</mthd> returns Uri String of field <code>httpConnector</code> +</p> +</li><li> + +<p><mthd>removeHttpConnector()</mthd> +<actn>stops <code>httpConnector</code></actn> +<actn>removes <code>httpConnector</code> from broker</actn></p> +</li><li> + +<p><mthd>addConnector(broker, type, basePort)</mthd> returns <code>TransportConnector</code> +<actn>starting with basePort, incr port till get a good return from broker.addConnector using localhost:port</actn></p> +</li><li> + +<p><mthd>getBrokerUri()</mthd> +<fld><code>uri</code></fld></p> +</li><li> + +<p><mthd>getConnection()</mthd> returns <code>Connection</code> from <code>uri</code></p> +</li><li> + +<p><mthd>createBroker( [port, useJmx, isSecondaryBroker])</mthd> returns BrokerService, used for main broker and 2ndry broker +<actn>broker uri <code>broker:()/localhost?persistent=false</code></actn> +<fld>sets <code>tcpConnector</code> to a tcp style connector at the port (default 61617)</fld> +<actn>if isSecondaryBroker, changes tcpConnector name and JmxDomainName gets ".test" added</actn> +</p> +</li><li> + +<p><mthd>setupSecondaryBroker(boolean addProperty)</mthd> returns broker instance +<actn>sets system property <code>activemq.broker.jmx.domain = org.apache.activemq.test</code></actn> +<actn>creates a secondary broker (calls <code>createBroker(61620, true, treu)</code> and starts it.</actn> +<actn>if addProperty, adds system property <code>BrokerURL</code></actn> +</p> +</li> +</ul> +<!-- ********************************************************************************************** --> +<!-- Base Test Support --> +<!-- ********************************************************************************************** --> +<h2>BaseTestSupport</h2> +<p>Inherits from ActiveMQSupport</p> + +<p><mthd>deployService(asyncEngine - to hold ref, deploydescriptorPath)</mthd> returns UUID string +<actn>uses SystemProp: BrokerURL or tcp://localhost:8118, sets defaultBrokerURL</actn></p> + +<p><mthd>addxceptionToIgnore, ignoreException</mthd></p> + +<p><mthd>initialize(asyncEngine, appCtx)</mthd> calls initialize on engine after adding statusCallbackListener of <code>listener</code> +which is set to a new instance of UimaAsTestCallbackListener, a subclass of this class</p> + +<p><mthd>buildContext(top-level-svc-broker-uri, top-level-queue-name, [timeout default 0])</mthd> returns appCtx map +<actn>sets CasPoolSize to 4, ReplyWindow to 15</actn></p> + +<p><mthd>isMetaRequest(Message)</mthd></p> + +<p><mthd>spinMonitorThread(ctrlSemaphore, howMany, kind)</mthd> returns thread that will wait +for howMany count-downs; returned threads are typically joined. +<fld>Kind/latches: <code>cpcLatch, exceptionCountLatch, processCountLatch</code></fld> </p> + + +<p><mthd>waitUntilInitialized()</mthd> signalled by callback, set up for one use per test instantiation +<fld><code>initializeMonitor, initialized</code></fld> + +<p><mthd>waitOnMonitor(Semaphore)</mthd> used to wait until all monitor threads are spun</p> + +<p><mthd>runTestWithMultipleThreads(svc-deploy-descr, q-name, how-many-CASes=per-thread, how-many-threads, +timeout, getmeta-timeout, [fail-on-timeout])</mthd> +<fld><code>engine</code> = new asyncEngine</fld> +<actn>deploy into engine, initialize engine</actn> +<actn>if <code>fail-on-timeout</code>, set timer task to undeploy in 5 seconds</actn> +<actn>spin up runner threads and have them send CASes, one at a time</actn> +<actn>wait till all CASes received, then wait till CPC done</actn> +</p> + +<p><mthd>runCrTest(engine, howMany)</mthd> Run using collection reader +<fld>set <code>engine</code> from the passed-in engine</fld> +<actn>The engine needs to be set up with a collection reader and + the standard listeners to count down the +PROCESS_LATCH</actn></p> + +<p><mthd>runTest(2)(appCtx, engine, brokerUri, q-name, howMany, latchKind, is-async-send)</mthd> +<fld>sets <code>engine</code></fld> +<actn>if latchKind is EXCEPTION_LATCH, use 1 thread for running client, +else use 2 - one for client, and one for CPC</actn> +<actn>if runTest, send all CASes at once (up to pool limit) up to howMany. +If runTest2, send each CAS 1 at a time, and wait until it is complete including CPC.</actn> +<actn>After <code>howMany</code> CASes, send CPC and wait for completion.</actn> +</p> + +<p><mthd>sendCAS(engine, howMany, isAsync)</mthd> +<actn>Gets CAS from casPool, sets doc txt, calls sendCas or SendAndReceiveCAS</actn></p> + + + +<p><mthd>spinShutdownThread(asyncEngine, when, [springContainerIds, stop_now or quiesce])</mthd> +<actn>after specified delay, tops either the async engine, or the deployed things. Used +to test recovery from svcs dying</actn></p> + +<h3>UimaTestCallbackListener</h3> +<p><mthd>onBeforeProcessCAS</mthd> writes logmsg to sysout</p> +<p><mthd>onBeforeMessageSend</mthd> writes Received ... notivication with CAS [casRefId] +<fld>sets casSent to casRefId) +</p> + +<p><mthd>onUimaAsServiceExit</mthd> logs msg with cause</p> + +<p><mthd>entityProcessComplete</mthd> might have performance metrics or not... +<actn>verifies (on exception) <code>receivedExpectedParentReferenceId</code></actn> +<actn>For successful test, gets processTraceEvents, checks duration is what's expected <code>expectedProcessTime</code> +<actn>For perform metrics: add per-component-performance-metrics to sysout log</actn> +</p> + +<p><mthd>isProcessTimeout</mthd></p> +<p><mthd>initializationComplete</mthd></p> +<p><mthd>collectionProcessComplete</mthd></p> + +<h3>SimpleCallbackListener</h3> +<p>extends UimaTestCallbackListener, overrides entityProcessComplete with a much simpler check/report</p> + + </body> + </html> + \ No newline at end of file