Administration
Replacement CQL Processor Developer Guide
This portion of the developer guide describes the steps for integrating the CQL_CSM library's replacement CQL processor with Introduce-generated data services that serve data from a relational database that contains data from a caCORE SDK-based application.
Test Environment
The replacement CQL processor was tested in an environment that consisted of the following components:
- The CENTOS 5.5 distribution of Linux (download
). - Java 1.5 (download)
- caGrid 1.3
- caCORE 4.1.1 (Versions before 4.1.1 will not be supported.) (download)
- PostgreSQL 8.1 (download) and MySql 5.0 (download) (in alternate environments. Not at the same time.)
Data Service Assumptions
The correctness of these implementation instructions and the correct performance of the replacement query processor rely on these assumptions:
- The data service does not use the caCORE SDK's writable API.
- The data service uses a database that has case-insensitive table names. The replacement CQL processor may not work correctly if table names are case sensitive. The CSM service that is used to administer CSM authorization policies will definitely not work correctly with case-sensistive table names (database that perform case sensitive comparisons on the contents of tables are not a problem). MySql on Linux can be made to have case-insensitive table names by setting the lower_case_table_names system variable to 1.
Naming Conventions
The instructions make the following assumptions about the names of some things:
*The root directory used to build and deploy the data service is identified as APP_LOCATION.
The top-level directory of the caGrid CSM support distribution is identified as CQL_CSM_LOCATION.
The name of the database whose data the data service accesses is represented in paths and file names as dbName.
The actual names that you use can vary, so long as you are consistent.
Step 1: Build the Support .jar Files
Issue these commands :
%CQL_CSM_LOCATION% }}
ant clean all |
| Linux & Macintosh |
cd $CQL_CSM_LOCATION ant clean all |
| Windows | cd %CQL_CSM_LOCATION% ant clean all |
Step 2: Generate the Data Service
Create an introduce-generated caGrid data service configured to access the data of a caCORE application through the "local" interface.
It does not matter if the data service is configured to use CSM security. However, if the data service is configured to use CSM security, be sure to note the value of the CSM_PROJECT_NAME property in the caCORE SDK's conf/deploy.properties file. You should to use this name for the application name when administering CSM security policies.
The data service should be deployed into a secure container.
At the time of this writing, Introduce support for caCORE SDK 4.1.1 appears to have a bug that causes it to not copy all of the needed .jar files from the generated package/local-client/lib directory. If you find that your data service is failing due to classes not being found, look for the missing .jar files in the generated package/local-client/lib directory and copy them to your data service's lib and build/lib directories. Files known to not be copied because of this bug include:
- ehcache-1.2.2.jar
- c3p0-0.9.0.jar
- mysql-connector-java-3.1.13-bin.jar
- jta.jar
- org.dom4j
- csmapi-4.1.jar
Note that because the data service is configured to use the local API, the data service works directly with the relevant database. The caGRID data service can run without the caCORE application running.
 | Caution Do not continue to the next step until this is working. |
Step 3: Clean out the Data Service's build Directory
Issue these commands :
| Linux & Macintosh |
cd $APP_LOCATION ant clean |
| Windows | cd %APP_LOCATION% ant clean |
Step 4: Make a Back-Up Copy of the APP_LOCATION Directory
In the following steps, you will be manually modifying the contents of files under the APP_LOCATION directory. In case something goes wrong you will save time by reverting the manually modified files to their previous state from the back-up.
Step 5: Copy the Replacement CQL Processor .jar to the Data Service
Issue these commands :
| Linux & Macintosh |
cp $CQL_CSM_LOCATION/build/lib/cql_csm_cacore_1.3.1.jar $APP_LOCATION/lib |
| Windows | copy %CQL_CSM_LOCATION%\build\lib\cql_csm_cacore_1.3.1.jar %APP_LOCATION%\lib |
Step 6: Modify the Contents of dbName?config.jar
In this step, you will be modifying the contents of an .jar file whose name follows the pattern $APP_LOCATION/lib/dbName?config.jar (for Linux/Macintosh) or %APP_LOCATION%\lib_dbName_?config.jar (for windows). For example, if the name of the database is jhusnpdb, then on Linux the actual file name will be $APP_LOCATION/lib/jhusnpdb?config.jar.
The recommended approach to editing .jar files is to extract the contents of the .jar file into a like-named subdirectory, edit the files in the subdirectories and then rebuild the .jar files. If you use an editor such as emacs that can edit files inside of a .jar file, that will also work.
Since there are multiple files withing the .jar file to be modified, this step is broken down into sub-steps.
Step 6.1: Edit application?config.xml in dbName?local?config.jar
Edit the XML for a spring bean that determines the class that the data service uses to process CQL queries. This is in a file named application?config.xml in the .jar file dbName?local?config.jar.
The application?config.xml file contains a spring bean that looks like this:
<bean name="ApplicationServiceImpl"class="gov.nih.nci.system.applicationservice.impl.ApplicationServiceImpl"singleton="true"> <constructor-arg ref="ClassCache"index="0"></constructor-arg> </bean>
Change the value of the class attribute from
gov.nih.nci.system.applicationservice.impl.ApplicationServiceImplto
edu.emory.cci.cqlCsm.cqlCsmHibernate.ApplicationServiceImpl
When you are done, the spring bean should look like this:
<bean name="ApplicationServiceImpl"class="edu.emory.cci.cqlCsm.cqlCsmHibernate.ApplicationServiceImpl"singleton="true"> <constructor-arg ref="ClassCache"index="0"></constructor-arg> </bean>
Further down in the file application?config.xml is another spring bean that looks like this:
<bean name="ClassCache"class="gov.nih.nci.system.util.ClassCache"singleton="true"> <property name="daoList"> <list> <!-- Add any DAO's here --> <ref bean="ORMDAOFactory"/> </list> </property> </bean>
The replacement CQL processor does not use or set up the environment needed for the ORMDAOFactory bean. Comment out the reference to it like this:
<bean name="ClassCache"class="gov.nih.nci.system.util.ClassCache"singleton="true"> <property name="daoList"> <list> <!-- Add any DAO's here --> <!-- <ref bean="ORMDAOFactory"/> --> </list> </property> </bean>
Further down in the application?config.xml file are additional spring beans named ORMDAO, HibernateConfigHolder, SessionFactory, SecurityInitializationHelper, HibernateTransactionManager and TxInterceptor. Delete these spring beans from the file.
Near the end of the application?config.xml file is a spring bean that looks like this:
<bean id="ApplicationService"class="org.springframework.aop.framework.ProxyFactoryBean"singleton="true"> <property name="target"ref="ApplicationServiceImpl"/> <property name="interfaces"value="gov.nih.nci.system.applicationservice.ApplicationService"/> <property name="interceptorNames"> <list> <idref local="TxInterceptor"/> <!--<idref local="CLMInterceptor"/>--> </list> </property> </bean>
Comment out the idref element so that it looks like this:
<bean id="ApplicationService"class="org.springframework.aop.framework.ProxyFactoryBean"singleton="true"> <property name="target"ref="ApplicationServiceImpl"/> <property name="interfaces"value="gov.nih.nci.system.applicationservice.ApplicationService"/> <property name="interceptorNames"> <list> <!-- <idref local="TxInterceptor"/> --> <!-- <idref local="CLMInterceptor"/> --> </list> </property> </bean>
This completes the edits for the file application?config.xml.
Step 6.2: Edit application-config-client.xml in dbName?local?config.jar
There is another XML file in $APP_LOCATION/lib/dbName?config.jar that needs to be edited. The name of the file is application-config-client.xml.
Find a spring bean in application-config-client.xml that looks like this
<bean id="ApplicationService"class="org.springframework.aop.framework.ProxyFactoryBean"singleton="true"> <property name="target"ref="ApplicationServiceImpl"/> <property name="interfaces"value="gov.nih.nci.system.applicationservice.ApplicationService"/> <property name="interceptorNames"> <list> <idref local="Interceptor"/> <idref bean="TxInterceptor"/> <!--<idref bean="CLMInterceptor"/>--> </list> </property> </bean>
Comment out the second idref element so that it looks like this:
<bean id="ApplicationService"class="org.springframework.aop.framework.ProxyFactoryBean"singleton="true"> <property name="target"ref="ApplicationServiceImpl"/> <property name="interfaces"value="gov.nih.nci.system.applicationservice.ApplicationService"/> <property name="interceptorNames"> <list> <idref local="Interceptor"/> <!--<idref bean="TxInterceptor"/>--> <!--<idref bean="CLMInterceptor"/>--> </list> </property> </bean>
Step 7:Install the CSM service
| Caution Read this installation step 8 completely (including step 8a or 8b as appropriate) before doing anything else! |
Install the version 1.3.1 of the CSM service on the same host as your data service. You will use this to administer instance level security and any other sorts of CSM security policies that you may be using. You can download the CSM service from the Inventrio downloads page.
The installation instructions for the CSM service describe a step titled, "Step 6: Initialize CSM database or tables (optional)". You will need to create CSM tables in the same database that your data service uses if they do not already exist.
The following paragraphs discuss some important details of how you should do initialize/create the CSM tables. If you are using PostgreSQL, then skip forward to section 8.2. Otherwise read the next section that talk about MySql.
Step 7.1: CSM Tables for MySql
If you are using a MySql database, be sure to use the command
ant createMysqlCsmTables
as described in the installation instructions to create the CSM tables in your existing database.
 | Danger Do not use the command ant createMysqlCsmDatabase which will delete your existing database!! |
If you are configuring your data service to use a different user ID to access the MySql database than the user ID that owns the CSM tables (recommended), you will need to grant select permission on the CSM tables to the user ID that the data service will be using. The names of these tables are:
- CSM_APPLICATION
- CSM_FILTER_CLAUSE
- CSM_GROUP
- CSM_PG_PE
- CSM_PRIVILEGE
- CSM_PROTECTION_ELEMENT
- CSM_PROTECTION_GROUP
- CSM_REMOTE_GROUP
- CSM_REMOTE_GROUP_SYNC_RECORD
- CSM_ROLE
- CSM_ROLE_PRIVILEGE
- CSM_USER
- CSM_USER_GROUP
- CSM_USER_GROUP_ROLE_PG
- CSM_USER_PE
You will also need to grant the user ID INSERT on the table CSM_APPLICATION.
This concludes the information on creating CSM tables in a MySql database. After you have just read this the first time, you should go to the beginning of Step 8 and begin the process of installing the CSM service. After you have finished installing the CSM service, proceed to step 9.
Step 7.2: CSM Tables for PostgreSQL
The process for creating the CSM database tables in a PosgreSQL database is not documented in the CSM service installation. The rest of this step discusses how to create the CSM tables for PostgreSQL.
Create three user IDs for the database:
- One user must be have the ID csm. This user must be created with CREATEDB. The csm user is the user will own the CSM tables. The csm user ID will not be used for any runtime or production purposes.
- One user must have the ID csm_adm. This user ID will be granted permissions needed to modify the contents of the CSM tables. The CSM service should be configured to use the csm_adm ID for connecting to the database.
- The other user must have the ID csm_app. This user ID will be granted read-only access to the CSM tables. Your data service should use the csm_app ID for connecting to the database.
In the CQL_CSM_LOCATION directory is a file named build.xml. Change the line in the file that looks like
<property name="csm.postgresql.csm.dbname"value="ivi_csm"/>
so that the value of the property is the name of the database your data service will be using. For example, if the name of the database is snpdb, then change the line to look like
<property name="csm.postgresql.csm.dbname"value="snpdb"/>
To create the CSM tables issue these commands:
| Linux & Macintosh |
cd $CQL_CSM_LOCATION ant createPostgresqlCsmTables |
| Windows | cd %CQL_CSM_LOCATION% ant createPostgresqlCsmTables |
The first time that you issue this command, it will prompt you for some information about your database. It collects this information in the file $CQL_CSM_LOCATION/CSM_pg/csm.properties. Subsequent times that you issue this command it will not prompt you for this information. Instead, it will read the stored information from the file. If you want to enter different information, then edit or delete the file.
When you have finished creating the CSM tables, you will also have created the file $CSM_CQL_LOCATION/CSM_pg/csm.properties. This file can be used to configure the CSM service. When you get to the place in the CSM service installation instructions where it tells you to edit a file named csm.properties you should first copy $CSM_CQL_LOCATION/CSM_pg/csm.properties over that file.
This concludes the information on creating CSM tables in a PostgreSQL database. After you have just read this the first time, you should go to the beginning of Step 8 and begin the process of installing the CSM service. After you have finished installing the CSM service, proceed to step 9.
Step 8: A csm.properties File for Your Data Service
Your data service will need a csm.properties file. If you are using a PostgreSQL database, you created a suitable csm.properties file in the previous installation step. If you are using a MySql database, then you will need to manually create a csm.properties file by copying the following sample.
csm.database.driver=com.mysql.jdbc.Driver csm.database.url=jdbc:mysql://localhost:3306/snpdbcsm.database.user=csm_app csm.database.password=xxx csm.appName=data_service
All of the properties in the sample must be present in the csm.properties file:
- csm.database.driverThe value of this should be the name of the class to use rfor the JDBC database driver. The usual value of this for a MySql database is com.mysql.jdbc.Driver.
- csm.database.urlThe value of this should be the URL to use for creating a JDBC connection to the database.
- csm.database.userThe user name that the data service should use for logging into the database.
- csm.database.passwordThe password that the data service should use for logging into the database.
- csm.appNameThe name to use to identify the data service in the CSM tables.
At this point you should have a csm.properties file, either from manually creating it or by automatically creating it with a script if you are using a PostgreSQL database. You need to copy your csm.properties file to the etc directory data service's build tree. If the root of your service's build directory structure is SVC then copy the csm.properties file to SVC/etc. Copying the csm.properties file to this directory will ensure that when you deploy the data service, the csm.properties file will be where your service can find it.
Step 9:Deploy the Data Service
cd to APP_LOCATION and issue the appropriate command to deploy the data service to its secure container.
Step 10: Start the Data Service's Container
Start the data service's container. If everything is working correctly, all of your functional tests for the data service should behave exactly as they did before you configured the data service to use the CQL_CSM replacement CQL processor. The way that CSM instance level security works is that until you configure at least one CSM filter for a class, unrestricted access to all of the class's instances is assumed.
| Performing this test step is not optional. Until you exercise the newly configured data service for the first time, it will not be registered in the CSM tables and you will not be able to configure CSM authorization policies for the data service. |
Step 11: Configure CSM Authorization Policies
You are now ready to configure CSM authorization policies for your data service.