Overview
This document is intended to supplement the Kuali Rice 2.1.2 Installation Guide and aid the creation of an embedded rice client application. The information on this page is targeted for the Rice 2.1.2 release.
Running a Rice client application in Embedded Mode means:
- one or more Rice modules - in particular, KEW and KIM - is are executing from within the client application
- the client application has direct access to the Rice Standalone Server database
...
- A database account with access to the Rice database
- Procure the UC Davis-specific JARs for the modules you will be embedding along with any of their associated dependencies using either of the following methods:
- Download
ucd-rice-standalone-server-impl
WAR from Artifactory , selecting the most recent version. This WAR contains all dependencies. - Download JARs for the specific module from this location in the Artifactory , selecting the most recent version.
- A certificate for the machine which machines hosting the client application that will be connection connecting to the Rice Standalone Server.
- Development Environments
- For the development environments, you may generate a self signed certificate and add to the attached rice.keystore using the following command:
Code Block |
---|
keytool -keystore rice.keystore -storepass nowUCme_nowUdont -v -alias <your alias> -genkeypair -validity 9999 -dname "CN=<your fully qualified machine name>, OU=<your organization>, O=UC Davis, L=Davis, ST=California, C=US"
|
- Install the updated rice.keystore in your environment where it will be referenced in the rice configuration files.
- A copy of the updated rice.keystore must also be installed on the Rice Standalone Server.
- An additional cert is required on the client development machine for access to the rice standalone development machine. A certificate from the rice standalone development machine must be imported into the java cacerts bundle on the client machine. The following command shows how to import the cert (attached) for the rice-sandboxes.ucdavis.edu development machine:
Code Block |
---|
keytool -importcert -file rice-sandboxes_ucdavis_edu.pem -keystore cacerts -storepass changeit -alias rice-sandboxes.ucdavis.edu
|
- Production Environment
- For the production environment, an InCommon Certificate is required for the machine(s) which will be connecting to the production Rice Standalone Server.
- The InCommon cert must be installed in the production rice keystore as well as the keystore of the client application.
For more information on how to request an InCommon certificate for your application, visit the following link and click on the SSL Certificate category: MyUCDavis > UCD Resources > Software See Rice Client Application Certificate Requirements for certificate details.
Rice Libraries
In Rice 1.0.x, there were only two main jars, rice-api and rice-impl. With the modularity work there are more api jars corresponding to service apis and framework components. Additionally, the implementation module has been split (though there is still a shared implementation module as not all components of the Rice implementation have been fully modularized as of the Rice 2.x.x release). This work was done according to the design outlined at the following page: Modularity Design
The libraries and their dependencies required for the modules which your application will be using must be included in your client application. Ideally you only declare include the modules of rice you are using. In practice, you may need to declare include them all until rice's modularity work is complete. The only modules rice recommends compiling against are api & framework modules.
...
We use a simple XML configuration to declare properties as key-value pairs. For example:
Code Block |
---|
borderStyle | solid |
---|
title | /usr/local/rice/rice-config.xml |
---|
borderStyle | solid |
---|
|
<config>
<param name="datasource.ojb.platform">Oracle9i</param>
<param name="datasource.platform">org.kuali.rice.core.framework.persistence.platform.OraclePlatform</param>
<param name="datasource.url">jdbc:oracle:thin:@ldap://oraldap1.ucdavis.edu:389/rice_test,cn=OracleContext,dc=ucdavis.edu,dc=edu</param>
<param name="datasource.driver.name">oracle.jdbc.driver.OracleDriver</param>
<param name="datasource.pool.validationQuery">select 1 from duak</param>
<param name="datasource.pool.maxWait">30000</param>
<param name="datasource.pool.size">30</param>
<param name="datasource.pool.maxActive">50</param>
<param name="datasource.minIdle">7</param>
<param name="datasource.initialSize">7</param>
<param name="datasource.accessToUnderlyingConnectionAllowed">true</param>
<param name="datasource.username">my_db_user</param>
<param name="datasource.password">my_db_password</param>
<config>
|
Info |
---|
title | Configuration File Options |
---|
|
- Default Rice Configuration
- By default Rice looks for
rice-config.xml in /usr/local/rice/ at launch time. Externalizing the configuration out to the file system allows us to substitute different values for different properties in different environments. We don't need to create a configuration file for say, the TEST vs. the PROD environment, and then build the application (i.e. the same WAR can be deployed in any instance). - See a set of sample properties .
Other Kuali Application Configurations - Other Kuali Application Configurations
- Kuali COEUS is a fully enabled rice application. The Kuali COEUS config file, kc-config.xml , is included here for reference.
|
Kuali Rice uses Java Open Transaction Manager, so we declare the appropriate beans.
Code Block |
---|
borderStyle | solid |
---|
title | classpath:edu/ucdavis/myapp/config/application-data.xml |
---|
borderStyle | solid |
---|
|
<bean id="jotm" class="org.springframework.transaction.jta.JotmFactoryBean">
<property name="defaultTimeout" value="${transaction.timeout}"/>
</bean>
|
...
- A transactional data source where the local client application's Rice tables are located. This is required by JOTM.
Code Block |
---|
borderStyle | solid |
---|
title | classpath:edu/ucdavis/myapp/config/application-data.xml |
---|
borderStyle | solid |
---|
|
<bean id="dataSource" class="org.kuali.rice.core.framework.persistence.jdbc.datasource.XAPoolDataSource">
<property name="transactionManager" ref="jotm" />
<property name="driverClassName" value="${datasource.driver.name}" />
<property name="url" value="${datasource.url}" />
<property name="maxSize" value="${datasource.pool.size}" />
<property name="minSize" value="${datasource.initialSize}" />
<property name="maxWait" value="${datasource.pool.maxWait}" />
<property name="validationQuery" value="${datasource.pool.validationQuery}" />
<property name="username" value="${datasource.username}" />
<property name="password" value="${datasource.password}" />
</bean>
|
- A non-transactional data source pointing to those same Rice tables. This is required by Quartz.
Code Block |
---|
borderStyle | solid |
---|
title | classpath:edu/ucdavis/myapp/config/application-data.xml |
---|
borderStyle | solid |
---|
|
<bean id="nonTransactionalDataSource" class="org.apache.commons.dbcp.BasicDataSource" destroy-method="close">
<property name="url" value="${datasource.url}"/>
<property name="username" value="${datasource.username}"/>
<property name="password" value="${datasource.password}"/>
<property name="driverClassName" value="${datasource.driver.name}" />
<property name="initialSize" value="${datasource.initialSize}" />
<property name="minIdle" value="${datasource.minIdle}" />
<property name="maxActive" value="${datasource.maxActive}" />
<property name="maxWait" value="${datasource.maxWait}" />
<property name="validationQuery" value="${datasource.validationQuery}" />
<property name="testOnBorrow" value="${datasource.testOnBorrow}" />
<property name="testOnReturn" value="${datasource.testOnReturn}" />
<property name="testWhileIdle" value="${datasource.testWhileIdle}" />
<property name="accessToUnderlyingConnectionAllowed" value="${datasource.accessToUnderlyingConnectionAllowed}" />
</bean>
|
Tip |
---|
To take advantage of pooling capabilities, testOnBorrow should be set to true . |
- A transactional data source pointing to the database of the Rice Standalone Server.
Code Block |
---|
borderStyle | solid |
---|
title | classpath:edu/ucdavis/myapp/config/application-data.xml |
---|
borderStyle | solid |
---|
|
<bean id="standaloneDataSource" class="org.kuali.rice.core.framework.persistence.jdbc.datasource.XAPoolDataSource">
<property name="transactionManager" ref="jotm" />
<property name="driverClassName" value="${standalone.datasource.driver.name}" />
<property name="url" value="${standalone.datasource.url}" />
<property name="maxSize" value="${standalone.datasource.pool.size}" />
<property name="minSize" value="${standalone.datasource.initialSize}" />
<property name="maxWait" value="${standalone.datasource.pool.maxWait}" />
<property name="validationQuery" value="${standalone.datasource.pool.validationQuery}" />
<property name="username" value="${standalone.datasource.username}" />
<property name="password" value="${standalone.datasource.password}" />
</bean>
|
...
Declare the UCD-implemented Rice services:
Code Block |
---|
borderStyle | solid |
---|
title | /usr/local/rice/rice-config.xml |
---|
borderStyle | solid |
---|
|
<param name="rice.kr.additionalSpringFiles">classpath:edu/ucdavis/kuali/rice/krad/config/ucd-krad-service.xml</param>
<param name="rice.kew.additionalSpringFiles">classpath:edu/ucdavis/kuali/rice/kew/config/ucd-kew-service.xml</param>
|
- If you're using Spring's
ContextLoaderListener
, declare them in web.xml
Code Block |
---|
borderStyle | solid |
---|
title | src/main/webapp/WEB-INF/web.xml |
---|
borderStyle | solid |
---|
|
<listener>
<listener-class>org.springframework.web.context.ContextLoaderListener</listener-class>
</listener>
<context-param>
<param-name>contextConfigLocation</param-name>param-name>
<param-value>
...
classpath:edu/ucdavis/kuali/rice/kim/config/ucd-krad-service.xml
<param-value>classpath:edu/ucdavis/kuali/rice/kew/config/ucd-kew-service.xml
...
</param-value>
</context-param>
|
CoreConfigurer Bean Configuration
Finally, we declare the coreConfigurer
bean and inject all of the core data source beans.
Code Block |
---|
title | classpath:edu/ucdavis/ |
---|
|
...
...
...
common.xml | borderStyle | solid |
---|
|
<bean |
...
id="coreConfigurer" class="org.kuali.rice.core.impl.config.module.CoreConfigurer">
<property name="dataSource" ref="dataSource" />
|
...
...
CoreConfigurer Bean Configuration
Finally, we declare the coreConfigurer
bean and inject all of the core data source beans.
Code Block |
---|
borderStyle | solid |
---|
title | classpath:edu/ucdavis/myapp/config/rice-common.xml |
---|
|
<property name="nonTransactionalDataSource" ref="nonTransactionalDataSource" />
<property name="serverDataSource" ref="standaloneDataSource"/>
<bean<property idname="coreConfigurertransactionManager" classref="org.kuali.rice.core.impl.config.module.CoreConfigurer"jotm" />
<property name="dataSourceuserTransaction" ref="dataSourcejotm" />
</bean>
<property<bean nameid="nonTransactionalDataSourceksbConfigurer" refclass="nonTransactionalDataSourceorg.kuali.rice.ksb.messaging.config.KSBConfigurer" />
<bean <property nameid="serverDataSourcekradConfigurer" refclass="standaloneDataSource"org.kuali.rice.krad.config.KRADConfigurer" />
<bean <property nameid="transactionManagercoreServiceConfigurer" refclass="jotmorg.kuali.rice.coreservice.impl.config.CoreServiceConfigurer" />
<bean <property nameid="userTransactionkimConfigurer" refclass="jotmorg.kuali.rice.kim.config.KIMConfigurer" />
</bean>
<bean id="ksbConfigurerkewConfigurer" class="org.kuali.rice.ksb.messagingkew.config.KSBConfigurer" depends-on="coreConfigurer"KEWConfigurer" />
<bean id="knsConfigurerkenConfigurer" class="org.kuali.rice.ken.kradimpl.config.KRADConfigurerKENConfigurer" depends-on="coreConfigurer"/>
<bean id="coreServiceConfigureredlConfigurer" class="org.kuali.rice.coreserviceedl.impl.config.CoreServiceConfigurerEDLConfigurer" depends-on="coreConfigurer"/>
<bean id="kimConfigurerkrmsConfigurer" class="org.kuali.rice.kimkrms.config.KIMConfigurerKRMSConfigurer" depends-on="coreConfigurer"/>
<bean id="kewConfigurerlocationConfigurer" class="org.kuali.rice.location.kewimpl.config.KEWConfigurerLocationConfigurer" depends-on="coreConfigurer"/>
|
Additional Rice Resources
- The Kuali Rice 2.1.2 Installation Guide
The installation guide contains useful information on all aspects of the Rice application from configuration of the standalone server to creation of a template rice client application and is a recommended additional resource for setting up your client application. If you use the maven command for creating a client application, be sure to update the -Darchetypeversion=2.1.2 Code Block |
---|
mvn archetype:generate -DarchetypeGroupId=org.kuali.rice -DarchetypeArtifactId=rice-archetype-quickstart -DarchetypeVersion=2.1.2
|
- The Kuali 2.1.2 Techincal Reference Guide
Recommended reading for understanding the overall Rice architecture.