Table of Contents |
---|
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
- LDAP Service Accounts on ldap.ucdavis.edu for dc=ucdavis,dc=edu and dc=it,dc=ucdavis,dc=edu trees.
- Procure the UC Davis-specific
rice-api
andrice-impl
JARs and all transitive 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. - Maven users: Add
ucd-rice-impl
as a dependency in your project (most likely the root POM).Code Block borderStyle solid title pom.xml <repositories> <repository> <id>ucd-maven</id> <name>UCD Maven Repository</name> <url>http://maven.ucdavis.edu/repo</url> </repository> </repositories> <properties> <ucd-rice-impl.version>[some UCD Rice Implementation version]</ucd-rice-impl.version> </properties> <dependencies> <dependency> <groupId>edu.ucdavis.kuali.rice</groupId> <artifactId>ucd-rice-impl</artifactId> <version>${ucd-rice-impl.version}</version> </dependency> </dependencies>
- Download
Properties Configuration
We use a simple XML configuration to declare properties as key-value pairs. For example:
Code Block | ||||
---|---|---|---|---|
| ||||
<config>
<param name="datasource.ojb.platform">Oracle</param>
<param name="datasource.platform">org.kuali.rice.core.database.platform.OraclePlatform</param>
<param name="datasource.url">jdbc:oracle:thin:@dbhost.ucdavis.edu:1521:SID</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 | ||
---|---|---|
| ||
|
Core Data Source Configuration
Kuali Rice uses Java Open Transaction Manager, so we declare the appropriate beans.
Code Block | ||||
---|---|---|---|---|
| ||||
<bean id="jotm" class="org.springframework.transaction.jta.JotmFactoryBean">
<property name="defaultTimeout" value="${transaction.timeout}"/>
</bean>
<bean id="jtaTransactionManager" class="org.springframework.transaction.jta.JtaTransactionManager">
<property name="transactionManager" ref="jotm"/>
<property name="userTransaction" ref="jotm"/>
</bean>
|
We must declare three data sources:
- 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 <bean id="dataSource" class="org.kuali.rice.core.database.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 <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 totrue
. - 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 <bean id="standaloneDataSource" class="org.kuali.rice.core.database.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>
KIM Service Configuration
The UCD KIM Identity Service fetches Entity and Principal information from UCD LDAP and, optionally, Display Name from White Pages. It is instantiated by declaring classpath:edu/ucdavis/kuali/rice/kim/config/ucd-kim-wp-service.xml
if using White Pages, or classpath:edu/ucdavis/kuali/rice/kim/config/ucd-kim-service.xml
if not using White Pages, in the Spring context.
Data Source Configuration
KIM Identity Service requires two LDAP data sources:
- A data source pointing to the
dc=ucdavis,dc=edu
tree to retrieve entries in theou=People
andou=Listings
schemas.Code Block borderStyle solid title classpath:edu/ucdavis/myapp/config/application-data.xml <bean id="ldapContextSource" class="org.springframework.ldap.core.support.LdapContextSource"> <property name="url" value="${ldap.url}" /> <property name="base" value="${ldap.base}" /> <property name="userDn" value="${ldap.user}" /> <property name="password" value="${ldap.password}" /> <property name="pooled" value="false" /> </bean>
- A data source pointing to the
dc=it,dc=ucdavis,dc=edu
tree server to retrieve entries in theou=Accounts
schema.Code Block borderStyle solid title classpath:edu/ucdavis/myapp/config/application-data.xml <bean id="ldapItContextSource" class="org.springframework.ldap.core.support.LdapContextSource"> <property name="url" value="${ldap.it.url}" /> <property name="base" value="${ldap.it.base}" /> <property name="userDn" value="${ldap.it.user}" /> <property name="password" value="${ldap.it.password}" /> <property name="pooled" value="false" /> </bean>
Optionally, KIM Identity Service provides access to the PEOPLE_DISPLAY_NAME
view in the ORG
schema in Mothra. whitePagesDataSource
...
borderStyle | solid |
---|---|
title | classpath:edu/ucdavis/myapp/config/application-data.xml |
...
- Download JARs for the specific module from this location in the Artifactory , selecting the most recent version.
- A certificate for the machines hosting the client application that will be connecting to the Rice Standalone Server.
- 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 include the modules of rice you are using. In practice, you may need to include them all until rice's modularity work is complete. The only modules rice recommends compiling against are api & framework modules.
Below is a list of the old 1.0.3.3 libraries and their 2.x.x counterparts:
Old Library | New Library |
---|---|
rice-api-1.0.3.3.jar | rice-core-api-2.x.x.jar |
 | rice-core-framework-2.x.x.jar |
 | rice-core-service-api-2.x.x.jar |
 | rice-core-service-framework-2.x.x.jar |
 | rice-edl-framework-2.x.x.jar |
 | rice-ken-api-2.x.x.jar |
 | rice-kew-api-2.x.x.jar |
 | rice-kew-framework-2.x.x.jar |
 | rice-kim-api-2.x.x.jar |
 | rice-kim-framework-2.x.x.jar |
 | rice-kns-2.x.x.jar |
 | rice-krad-app-framework-2.x.x.jar |
 | rice-krad-web-framework-2.x.x.jar |
 | rice-krms-api-2.x.x.jar |
 | rice-krms-framework-2.x.x.jar |
 | rice-ksb-api-2.x.x.jar |
 | rice-location-api-2.x.x.jar |
 | rice-location-framework-2.x.x.jar |
rice-impl-1.0.3.3.jar | rice-impl-2.x.x.jar |
 | rice-core-impl-2.x.x.jar |
 | rice-core-service-impl-2.x.x.jar |
 | rice-edl-impl-2.x.x.jar |
 | rice-kew-impl-2.x.x.jar |
 | rice-kim-impl-2.x.x.jar |
 | rice-krms-impl-2.x.x.jar |
 | rice-ksb-client-impl-2.x.x.jar |
 | rice-ksb-server-impl-2.x.x.jar |
 | rice-location-impl-2.x.x.jar |
rice-sampleapp-1.0.3.3.jar | rice-core-service-web-2.x.x.jar |
 | rice-core-web-2.x.x.jar |
 | rice-ksb-web-2.x.x.jar |
 | rice-location-web-2.x.x.jar |
Properties Configuration
We use a simple XML configuration to declare properties as key-value pairs. For example:
Code Block | ||||
---|---|---|---|---|
| ||||
<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,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 | ||
---|---|---|
| ||
|
Core Data Source Configuration
Kuali Rice uses Java Open Transaction Manager, so we declare the appropriate beans.
Code Block | ||||
---|---|---|---|---|
| ||||
<bean id="jotm" class="org.springframework.transaction.jta.JotmFactoryBean"> <property name="passworddefaultTimeout" value="${whitepagestransaction.datasource.passwordtimeout}"/> </bean> |
We must declare three data sources:
- A transactional data source where the local client application's Rice tables are located. This is required by JOTM.
Code Block 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
...
Tip |
---|
To take advantage of pooling capabilities, |
KEW Service Configuration
...
.password}" /> </bean>
- A non-transactional data source pointing to those same Rice tables. This is required by Quartz.
Code Block title classpath:edu/ucdavis/
...
myapp/config/
...
application-
...
data.xml
...
Consequently, the encryption.key
property is no longer required.
KNS Service Configuration
- Maintenance Document Encryption
- As of 1.0.1.1-UCD-SR1d, Rice applications will no longer encrypt maintenance document content.
- This is accomplished by disabling encryption using the out-of-the-box non-encryption implementation (
org.kuali.rice.core.service.impl.NoEncryptionEncryptionServiceImpl
). - Disable encryption by declaring the
classpath:edu/ucdavis/kuali/rice/kim/config/ucd-kns-service.xml
Spring file (see UCD Spring Bean Configuration). - Remove (or comment out) references to the
encryption.key
property (e.g. in rice-config.xml, kc-config.xml, embedded-client-config.xml, etc.).
- Configure Rice Application Configuration Service
- A client application must declare which package prefixes it is responsible for servicing.
- If not, then it will by default, try to handle requests over the service bus for Rice objects (those prefixed with
org.kuali.rice
). - The
application.url
needs to be set such that the requester knows which server is handling the request. Override the Rice Application Configuration Service like so: - A transactional data source pointing to the database of the Rice Standalone Server.
kns.service.impl.RiceApplicationConfigurationServiceImplCode Block title classpath:edu/ucdavis/myapp/config/application-data.xml borderStyle solid <bean id="standaloneDataSource" class="org.kuali.rice.
packagePrefixescore.framework.persistence.jdbc.datasource.XAPoolDataSource"> <property name="
>transactionManager"
<list> <value>edu.ucdavis.myapplicationprefix</value> </list>ref="jotm" /> <property
</property> </bean>name="driverClassName" value="${standalone.datasource.driver.name}" />
Code Block | ||||
---|---|---|---|---|
| ||||
<param name="application.url">https://myappserver.ucdavis.edu/</param>
|
borderStyle | solid |
---|---|
title | myRiceSpringBeans.xml |
| |||
<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, |
UCD Spring Bean Configuration
Declare the UCD-implemented Rice services using either of the following methods:
- Declare them as part of the
rice.additionalSpringFiles
property and pass that as a token into therice
beanCode Block borderStyle solid title /usr/local/rice/rice-config.xml <param name="rice.additionalSpringFiles">classpath:edu/ucdavis/kuali/rice/kim/config/ucd-kim-service.xml,classpath:edu/ucdavis/kuali/rice/kim/config/ucd-kew-service.xml,classpath:edu/ucdavis/kuali/rice/kim/config/ucd-kns-service.xml</param>
Declare them directly in theCode Block borderStyle solid title classpath:edu/ucdavis/myapp/config/rice-common.xml <bean id="rice" class="org.kuali.rice.core.config.RiceConfigurer"> ...<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="additionalSpringFilesvalidationQuery"> value="${standalone.datasource.pool.validationQuery}" /> <property <value>${rice.additionalSpringFiles}</value>name="username" value="${standalone.datasource.username}" /> </property> ...<property name="password" value="${standalone.datasource.password}" /> </bean>
rice
bean using theadditionalSpringFiles
property (see Rice Bean Configuration)Code Block borderStyle solid title
KEW Service Configuration
As of 1.0.1.1-UCD-SR1d, Rice applications will no longer encrypt workflow document content. This is accomplished by disabling encryption using the out-of-the-box non-encryption implementation (org.kuali.rice.core.impl.encryption.NoEncryptionEncryptionServiceImpl
). It is instantiated by declaring classpath:edu/ucdavis/
...
kuali/rice/kew/config/
...
ucd-kew-
...
service.xml
in the Spring context.
Consequently, the encryption.key
property is no longer required.
KRAD Service Configuration
- Maintenance Document Encryption
- As of 1.0.1.1-UCD-SR1d, Rice applications will no longer encrypt maintenance document content.
- This is accomplished by disabling encryption using the out-of-the-box non-encryption implementation (
org.kuali.rice.core.impl.encryption.NoEncryptionEncryptionServiceImpl
). - Disable encryption by declaring the
classpath:edu/ucdavis/kuali/rice/
krad/config/ucd-
krad-service.
ContextLoaderListener
, declare them inweb.xml
Code Block <listener> <listener-class>org.springframework.web.context.ContextLoaderListener</listener-class> </listener> <context-param> <param-name>contextConfigLocation</param-name> <param-value> ... classpathborderStyle solid title src/main/webapp/WEB-INF/web.xml xml
Spring file (see UCD Spring Bean Configuration).- Remove (or comment out) references to the
encryption.key
property (e.g. in rice-config.xml, kc-config.xml, embedded-client-config.xml, etc.).
UCD Spring Bean Configuration
Declare the UCD-implemented Rice services:
Code Block | ||||
---|---|---|---|---|
| ||||
<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 inweb.xml
Code Block 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-value> ... </param-value> </context-param>
Rice Bean Configuration
Finally, we declare the rice
bean and inject all of the core data source beans into it along with any required additional Spring files.
...
classpath:edu/ucdavis/
...
kuali/rice/kim/config/
...
ucd-krad-
...
service.xml
...
...
...
...
...
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 | ||||
---|---|---|---|---|
| ||||
<property<bean nameid="userTransactioncoreConfigurer" refclass="jotm" /org.kuali.rice.core.impl.config.module.CoreConfigurer"> <property name="serviceNamespacedataSource" valueref="${service.namespace}dataSource" /> <property name="environmentnonTransactionalDataSource" valueref="${environment}nonTransactionalDataSource" /> <property name="rootConfigserverDataSource" ref="configstandaloneDataSource" /> <property name="ksbConfigurertransactionManager"> <bean class="org.kuali.rice.ksb.messaging.config.KSBConfigurer"> ref="jotm" /> <property name="serviceServletUrluserTransaction" valueref="${serviceServletUrl}jotm" /> </bean> <bean </property>id="ksbConfigurer" class="org.kuali.rice.ksb.messaging.config.KSBConfigurer" /> <bean <property nameid="kewConfigurerkradConfigurer"> class="org.kuali.rice.krad.config.KRADConfigurer" /> <bean <bean id="coreServiceConfigurer" class="org.kuali.rice.coreservice.kewimpl.config.KEWConfigurerCoreServiceConfigurer" /> <bean id="kimConfigurer" class="org.kuali.rice.kim.config.KIMConfigurer" /> <property name<bean id="clientProtocolkewConfigurer" valueclass="localorg.kuali.rice.kew.config.KEWConfigurer" /> <bean </bean>id="kenConfigurer" class="org.kuali.rice.ken.impl.config.KENConfigurer" /> <bean </property> <property name="knsConfigurer"> <beanid="edlConfigurer" class="org.kuali.rice.edl.impl.config.EDLConfigurer" /> <bean id="krmsConfigurer" class="org.kuali.rice.knskrms.config.KNSConfigurerKRMSConfigurer" /> </property> <property name<bean id="kimConfigurerlocationConfigurer"> <bean class="org.kuali.rice.location.kimimpl.config.KIMConfigurer"/> </property> <property name="kcbConfigurer"> <bean class="org.kuali.rice.kcb.config.KCBConfigurer"/> </property> <property name="additionalSpringFiles"> <value>${rice.additionalSpringFiles}</value> </property> </bean> LocationConfigurer" /> |
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.2Code 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.