Prerequisites

[ epicsarchiverap ]$ echo $TOMCAT_HOME
/opt/local/tomcat/latest
[ epicsarchiverap ]$ ls -l $TOMCAT_HOME/
drwxr-x---   3 mshankar cd  4096 Oct 29 18:25 bin
-rw-r-----   1 mshankar cd 19182 May  3  2019 BUILDING.txt
drwx------   3 mshankar cd   254 Jul 29 14:41 conf
drwx------   2 mshankar cd   238 May 22 15:43 conf_from_install
drwxr-xr-x+  2 mshankar cd   238 May 22 15:44 conf_original
-rw-r-----   1 mshankar cd  5407 May  3  2019 CONTRIBUTING.md
drwxr-x---   2 mshankar cd  4096 Sep 17 18:13 lib
-rw-r-----   1 mshankar cd 57092 May  3  2019 LICENSE
drwxr-x---   2 mshankar cd   193 Nov 11 16:58 logs
-rw-r-----   1 mshankar cd  2333 May  3  2019 NOTICE
-rw-r-----   1 mshankar cd  3255 May  3  2019 README.md
-rw-r-----   1 mshankar cd  6852 May  3  2019 RELEASE-NOTES
-rw-r-----   1 mshankar cd 16262 May  3  2019 RUNNING.txt
drwxr-x---   2 mshankar cd    30 Sep 17 18:19 temp
drwxr-x---  11 mshankar cd   205 Nov 11 16:58 webapps
drwxr-x---   3 mshankar cd    22 May 22 15:55 work
[ epicsarchiverap ]$

    <Connector port="17665" protocol="HTTP/1.1" 
               connectionTimeout="20000" 
               redirectPort="8443" />

cd ${TOMCAT_HOME}
cp -R conf conf_original

Building

[ epicsarchiverap ]$ ant
Buildfile: /workspace/epicsarchiverap/build.xml
     [echo] Building the archiver appliance for the site tests
...
wars:
      [tar] Building tar: /workspace/archappl_v0.0.1_SNAPSHOT_13-November-2019T14-48-26.tar.gz

BUILD SUCCESSFUL
Total time: 21 seconds
[ epicsarchiverap ]$ 

[ epicsarchiverap ]$ ls -ltra ../archappl_*.tar.gz
-rw-r--r-- 1 mshankar cd 154000860 Nov 13 14:48 ../archappl_v0.0.1_SNAPSHOT_13-November-2019T14-48-26.tar.gz
[ epicsarchiverap ]$ 

Deploying

pushd ${TOMCAT_HOME}/webapps && rm -rf retrieval* && popd && cp ../retrieval.war ${TOMCAT_HOME}/webapps
pushd ${TOMCAT_HOME}/webapps && rm -rf engine* && popd && cp ../engine.war ${TOMCAT_HOME}/webapps
pushd ${TOMCAT_HOME}/webapps && rm -rf etl* && popd && cp ../etl.war ${TOMCAT_HOME}/webapps
pushd ${TOMCAT_HOME}/webapps && rm -rf mgmt* && popd && cp ../mgmt.war ${TOMCAT_HOME}/webapps

export ARCHAPPL_SHORT_TERM_FOLDER=/arch/sts/ArchiverStore
export ARCHAPPL_MEDIUM_TERM_FOLDER=/arch/mts/ArchiverStore
export ARCHAPPL_LONG_TERM_FOLDER=/arch/lts/ArchiverStore

Running Tomcat

Running the unit tests

With Gradle

gradle test // Runs all unit tests except slow tests
gradle unitTests // Runs all unit tests
gradle integrationTests // Runs all tests that require a tomcat installation and/or epics installation
gradle flakyTests // Runs all tests that can fail due to system resources
gradle allTests // Runs all tests (not recommended)

gradle test -tests PolicyExecutionTest
gradle integrationTests --tests PvaGetArchivedPVsTest --info

With Ant

export ARCHAPPL_SHORT_TERM_FOLDER=/arch/sts/ArchiverStore
export ARCHAPPL_MEDIUM_TERM_FOLDER=/arch/mts/ArchiverStore
export ARCHAPPL_LONG_TERM_FOLDER=/arch/lts/ArchiverStore

cd ${TOMCAT_HOME}
cp -R conf conf_original

ant; ant -Dtest=DBRTypeTest singletest

ant; ant -Dverboselogging=true -Dtest=DBRTypeTest singletest

Side projects

1. PB/HTTP
2. Archive Viewer

Information useful to developers

1. Here's a document on the steps to follow when bundling JCA with the EPICS archiver appliance.
2. If you unfamiliar with servlet containers; here's a small overview that a few collaborators found useful
   • Reading up on a few basics will help; there are several good sources of information on the net; but don't get bogged down by the details.
   • Please do use Eclipse/Netbeans to navigate the code. This makes life so much easier.
   • To get a quick sense of what a class/interface does, you can use the javadoc. Some attempts have been made to have some Javadoc in most classes and all interfaces
   • We use Tomcat purely as a servlet container; that is, a quick way of servicing HTTP requests using Java code.
   • A WAR file is basically a ZIP file (you can use unzip) with some conventions. For example, all the libraries (.jar's) that the application depends on will be located in the WEB-INF/lib folder.
   • The starting point for servlet's in a WAR file is the file WEB-INF/web.xml. For example, in the mgmt.war's WEB-INF/web.xml, you can see that all HTTP requests matching the pattern /bpl/* are satisfied using the Java class org.epics.archiverappliance.mgmt.BPLServlet.
   • If you navigate to this class in Eclipse, you'll see that it is basically a registry of BPLActions.
   • For example, the HTTP request, /mgmt/bpl/getAllPVs is satisfied using the GetAllPVs class. Breaking this down,
     1. /mgmt gets you into the mgmt.war file.
     2. /bpl gets you into the BPLServlet class.
     3. /getAllPVs gets you into the GetAllPVs class.
   • From a very high level
     • The engine.war establishes Channel Access monitors and then writes the data into the short term store (STS).
     • The etl.war file moves data between stores - that is from the STS to the MTS and from the MTS to the LTS and so on.
     • The retrieval.war gathers data from all the stores, stitches them together to satisfy data retrieval requests.
     • The mgmt.war manages all the other three and holds configuration state.
   • In terms of configuration, the most important is the PVTypeInfo; you can see what one looks like by looking at http://machine:17665/mgmt/bpl/getPVTypeInfo?pv=MYPV:111:BDES
   • The main interfaces are the ones in the org.epics.archiverappliance package.
   • The ConfigService class does all configuration management.
   • The customization guide is also a good guide to way in which this product can be customized.