app-manager

app-manager contains code to invoke and monitor ApPredict.

app-manager was designed to enable the isolation of ApPredict invocation so that any client (e.g. a WS-invoking Perl script similar to query_business_manager_WSS.pl - not necessarily either of the AP-Portal site-business and/or client-direct components) could call it to run ApPredict.
It was also isolated so that it could reside on hardware which was able to run many concurrent invocations, e.g. on a workstation with a lot of RAM and processors, without degrading the client’s response times.

Below is a diagrammatic representation app-manager ApPredict invocation operations (see tools/prepare_<appredict_invocation_mechanism>.sh, tools/local_runner.sh and tools/<appredict_invocation_mechanism>.sh for more info).

app-manager overview

Dependencies

  • Maven (build)
  • Java 7 or higher (build, deploy)
  • Java Servlet Container, e.g. Apache Tomcat (deploy)
  • Database (build, deploy)

Initial installation

Download the project source and go to this component’s root directory (i.e. here) and follow the steps below.

  • Either …
  • … or …
  1. [ T ] Copy sample.pom.xml to pom.xml
  2. [ T ] Copy src/main/resources/META-INF/spring/ctx/ws/sample.appCtx.ws.security-incoming.xml to src/main/resources/META-INF/spring/ctx/ws/appCtx.ws.security-incoming.xml
  3. [ T ] Copy src/main/resources/META-INF/spring/ctx/ws/sample.appCtx.ws.security-outgoing.xml to src/main/resources/META-INF/spring/ctx/ws/appCtx.ws.security-outgoing.xml
  4. [ T ] Copy src/properties/database/sample.database.filter.properties to src/properties/database/database.filter.properties
  5. [ T ] Copy src/properties/sample.filter.properties to src/properties/filter.properties
  6. [ T ] Copy src/properties/sample.spring.properties to src/properties/spring.properties
  • … then …

  1. Follow database choice instructions.

  2. [ T ] Copy the bash shell scripts and RelaxNG schema files, e.g. …

    1. *.sh
    2. mathml2.rng

    … from /app-manager/tools/ to your equivalent of Tomcat’s CATALINA_HOME.
    Continue to read tools/prepare_<appredict_invocation_mechanism>.sh, tools/local_runner.sh and tools/<appredict_invocation_mechanism>.sh for further configuration instructions.

  3. [ T ] Create the directory procdir in your equivalent of Tomcat’s CATALINA_HOME

  • … finally
  1. Edit each of the copied files according to your desired configuration.

Configuration

pom.xml

It is likely that there is a site-specific database driver (such as a MySQL driver) which needs adding to the pom.xml file.

src/properties/filter.properties

app.soap.location=

WS URL of this component, e.g. ‘http://localhost:18380/app_manager-0.0.4/aws/’

app.soap.wsdl=

This component’s WSDL name, e.g. ‘app_services.wsdl’
The combination of app.soap.location and app.soap.wsdl, e.g. ‘http://localhost:18380/app_manager-0.0.4/aws/app_services.wsdl’ should reveal the SOAP web service when the component is running.

business.soap.location=

WS URL of site-business component, e.g. ‘http://localhost:18080/site_business-0.0.2/bws/’

log.file=

Component log file location on disk, e.g. ‘logs/app-manager.log’

log.level.app_manager=

Log level of this component, e.g. (trace|debug|info|warn|error|fatal).

log.level.non_app_manager

Log level of code from other libraries, e.g. (trace|debug|info|warn|error|fatal).

src/properties/spring.properties

base.dir=

Directory used as abase for ApPredict invocations, e.g. ‘/home/user/app_run/’

Warning

Assign cautiously! ApPredict is invoked in subdirectories of this directory and these subdirectories are created and destroyed (by PostSimulationRunTidyUp.java) as appropriate.

monitor.frequency=

Simulation process monitoring frequency (in seconds), e.g. ‘15’.

invocation.limit=

Maximum number of concurrent ApPredict invocations, e.g. ‘8’.

securement.app.username=

Component WSS username.

securement.app.password=

Component WSS password.

securement.business.username=

site-business WSS username.

securement.business.password=

site-business WSS password.

src/main/resources/META-INF/spring/ctx/ws/appCtx.ws.security-incoming.xml

Generally no change necessary.

src/main/resources/META-INF/spring/ctx/ws/appCtx.ws.security-outgoing.xml

Generally no change necessary.

src/properties/database/database.filter.properties

Generally no change necessary.

src/properties/database/dev.database.<deploy.db_vendor>.properties

See also

Database choice

tools/prepare_<appredict_invocation_mechanism>.sh

One of the following files will be your simulation preparation script of choice according to your local ApPredict installation.

  1. prepare_docker.sh
  2. prepare_localfs.sh
  3. prepare_singularity.sh

Its role generally is to copy across (or symlink) the ApPredict invoker of choice file (see tools/<appredict_invocation_mechanism>.sh) into the directory in which the simulation will run (i.e. a subdirectory of base.dir (as defined in src/properties/spring.properties’ base.dir)), and to swap a couple of placeholder values therein.

The name prepare.sh is hardcoded into ApPredictRunPreProcessor.java, and therefore depending on how you intend to run ApPredict you will need to symlink one of above files to prepare.sh, as below …

CATALINA_HOME directory listing

tools/local_runner.sh

You shouldn’t need to make any changes to this file.

The name local_runner.sh is hardcoded in ApPredictInvoker.java.

https://bitbucket.org/gef_work/ap_predict_online/src/master/app-manager/tools/local_runner.sh is the script that will be called by ApPredictInvoker.java and it will …

  1. cd to the local filesystem dir (as determined by the base.dir property and job identifier), then
  2. run whichever ApPredict.sh wrapper script (as derived from ApPredict.sh, Singularity.sh or Docker.sh) which will in turn invoke the ApPredict binary.
  3. It will also generate the VRE_INFO and VRE_OUTPUT files, the former contains general environment info, the latter contains the stdout and stderr from the invocation, both of which get persisted if the simulation runs successfully.

tools/<appredict_invocation_mechanism>.sh

One of the following files will be your ApPredict invoker of choice for your installation. The content of which you may need to modify according to your local ApPredict installation.

  1. ApPredict.sh
  2. Singularity.sh
  3. Docker.sh

The name ApPredict.sh is hardcoded in ApPredictInvoker.java, and therefore you need to have symlinked your relevant prepare_<appredict_invocation_mechanism>.sh to prepare.sh (as explained in tools/prepare_<appredict_invocation_mechanism>.sh), such that the ApPredict invoker of choice wrapper script will be used (via an invocation of local_runner.sh).

procdir

procdir is used to deposit system process data into files which can be read by the application for the purpose of monitoring the system process state, i.e. to determine if ApPredict is still running.
It is hardcoded in two places :

  1. File appCtx.int.processMonitoring.xml has hardcoded (in int-file:inbound-channel-adapter) the directory procdir where the application expects system process data files to be deposited by the system at runtime upon ApPredict invocation.
  2. local_runner.sh also has the same hardcoding.

Build

See also

Database choice and Spring profiles for additional information.

-Dspring.profiles.active=

Options are currently app_manager_(embedded|mysql|oracle10g).

Warning

At build time it is important to use the -Dspring.profiles.active=app_manager_embedded arg because during integration testing rubbish may be written to the database so it is important to use the embedded database during this process.

-Ddeploy.db_vendor=

The name of the database vendor, e.g. mysql, postgres, used in the intended deployment (not build) environment. The actual name used corresponds exactly to the <deploy.db_vendor> element of the file derived from sample.database.spring.properties during the installation process.

-Ddeploy.env=

The environment name, i.e. dev.

Example build instructions (illustrating use of embedded during the build process, and mysql in the deploy environment):

cd <ap_predict_online>/app-manager
mvn clean verify -Dspring.profiles.active=app_manager_embedded -Ddeploy.db_vendor=mysql -Ddeploy.env=dev

Deploy

If the build command has completed successfully the webapp .war file should be in the target directory. Copy this to the servlet container’s relevant file, e.g for Tomcat, the webapps directory.

Run

See start.

Start-up problems

Property 'driverClassName' threw exception; nested exception is java.lang.IllegalStateException: Could not load JDBC driver class [appCtx.database.xml_unassigned]

Probably means that the mvn build command had the wrong combination of -Ddeploy.db_vendor= and/or -Ddeploy.env= values assigned.
What generally happens is that the pom.xml generate-resources phase will concatenate two properties files into src/main/resources/META-INF/properties/app_manager.properties but if the wrong (or no) database properties file is referenced then the database properties will be missing.

No bean named 'appDataSource' is defined

It could be that wrong JAVA_OPTS value for spring.profiles.active is being set prior to the component being started, e.g. JAVA_OPTS="-Dspring.profiles.active=app_manager_myyysql".

Various notes

See JASYPT use.