Kuali Rice 2.3.0-M2-SNAPSHOT Kuali Service Bus

The Kuali Service Bus (KSB) is a lightweight service bus designed to allow developers to quickly develop and deploy services for remote and local consumption. You can deploy services to the bus using Spring or programmatically. Services must be named when they are deployed to the bus. Services are acquired from the bus using their name.

At the heart of the KSB is a service registry. This registry is a listing of all services available for consumption on the bus. The registry provides the bus with the information necessary to achieve load balancing, failover, and more.

Figure 1.1. Kuali Service Bus

You can deploy services to the bus using Spring or programmatically. Services must be named when they are deployed to the bus. Services are acquired from the bus using their name.

Overview of Supported Service Protocols

Figure 1.2. Supported Service Protocols

This drawing is conceptual and not representative of true deployment architecture. Essentially, the KSB is a registry with service-calling behavior on the client end (Java client). All policies and behaviors (async as opposed to sync) are coordinated on the client. The client offers some very attractive messaging features:

• Synchronization of message sending with currently running transaction (meaning all messages sent during a transaction are ONLY sent if the transaction is successfully committed)

• Failover - If a call to a service comes back with a 404 (or various other network-related errors), it will try to call other services of the same name on the bus. This is for both sync and async calls.

• Load balancing - Clients will round-robin call services of the same name on the bus. Proxy instances, however, are bound to single machines if you want to keep a line of communication open to a single machine for long periods of time.

• Topics and Queues

• Persistent messages - When using message persistence a message cannot be lost. It will be persisted until it is sent.

• Message Driven Service Execution - Bind standard JavaBean services to messaging queues for message driven beans.

The message filter and fetch section of the Message Queue screen lets you search for, filter, and/or isolate messages in the Documents in route queue. To use the Message Filter section, enter your criteria and click the Filter button:

Figure 2.2. Message Filter Screen

The Execute Message Fetcher button retrieves all the messages in the route queue. You can adjust the number of messages requested by entering a number in the field left of the button.

When you click the Execute Message Fetcher button, a dialog box appears, confirming that you want to execute this command:

Figure 2.3. Execute Message Filter: Confirmation Screen

KSB displays the results of a search and/or filter at the bottom of the page in the Documents currently in route queue table.

Figure 2.4. Documents In Route Queue

When you click View in the Actions menu, KSB displays information about that message. Most of the initial information is the same as that displayed in the Documents currently in route queue table. Additional information on the View screen:

To lock a document via the default Pessimistic Locking mechanism means that the document is locked by a user prior to any changes the user may perform. The traditional setup of documents in Rice is to lock them using Optimistic Locking where two users may edit a document at the same time. However, the first user to take an action that will save the document will 'win', and the second user will see an error saying that the document was edited by another user. For Pessimistic Locking, the first user who has edit privileges will get a lock on the document, and any subsequent users who should have edit privileges on the document, who try to view the document, will only get read-only access to the document, until the first user's lock is 'released'.

There are two places in Rice where Pessimistic Locks can be used:

The default implementation for locking a document for user entry tells the system to place a lock on a document if a user attempts to view it and that user has one or more 'entry' type edit modes as defined by the document's Document Authorizer class. Once the lock is placed, any other user who should have 'entry' privileges on the document will not be allowed to do so until the lock by the first user is released.

To enable Pessimistic Locking on a document the attribute 'usePessimisticLocking' must be set to 'true' in the transactional document's entry.

Example:

<dictionaryEntry>
    <transactionalDocument>
        ...
        <usePessimisticLocking>true</usePessimisticLocking>
        ...
    </transactionalDocument>
</dictionaryEntry>

For extremely complex customization that goes beyond what may be described in this document a client developer can look at the javadocs of the org.kuali.core.document.authorization.DocumentAuthorizerBase class paying special attention to the methods below:

The completely override the lock handling the Document Authorizer method establishLocks(Document, Map, UniversalUser) can be overriden.

If the Transactional Document that will be using Pessimistic Locking has a custom Document Authorizer class and uses custom edit modes returned by the getEditMode(Document, UniversalUser) method, the custom authorizer class should also override the method isEntryEditMode(Map.Entry) . If the entry parameter passed in is defined as a valid 'entry' mode then the method should return true.

The default Pessimistic Lock implementation does not use Lock Descriptors so only one person may have a lock on a single document at any one time. If something more custom is required Lock Descriptors can be used. The default implementation of a document that uses Pessimistic Locking and custom Lock Descriptors is that once a single user establishes a lock on a certain document with a certain lock descriptor... no other user can create a lock on that document with that descriptor. If another user needs that lock created they will have read only access on the document until the other user releases their lock.

Example

As an example, think of a document that has both an Delivery section and a Billing section. Perhaps a user 'fred' has access to edit the Delivery section but not the Billing section. Likewise, a user 'francine' has access to edit the Billing section but not the Delivery section. In this case it would be possible for both 'francine' and 'fred' to each have a lock on a single document since the data they have editable is mutually exclusive from the other. In this example 'fred' could have a Pessimistic Lock with a descriptor 'Delivery' while 'francine' could have a Pessimistic Lock with a 'Billing' descriptor.

To use lock descriptors the client application document should implement a custom Document Authorizer class if not done already (see Authorizers - Client Developer Guide (0.9.3) for more information). The authorizer class should override the useCustomLockDescriptors() method to return true. The method getCustomLockDescriptor(Document, Map, UniversalUser) must also be overriden to return the value of the desired lock descriptor. It's up to the client to determine how to set these and what values to use.

The default implementation for locking a document for processing by Workflow tells the system to place a lock on a document once a Workflow action is taken if that Workflow action is not contained in a list (see Default Workflow Actions that Don't Require Locks). The default user that will 'own' the lock will be the Rice System User. Once the lock is placed, any other user who should have 'entry' privileges on the document will not be allowed to do so until the lock is released. Locks for Workflow processing are released once the Workflow process completes successfully.

The following actions in Workflow will not set up a Pessimistic Lock for the coinciding process:

To enable Pessimistic Locking for Workflow operations on a document the attribute useWorkflowPessimisticLocking must be set to 'true' in the transactional document's entry.

Example

<dictionaryEntry>
    <transactionalDocument>
        ...
        <useWorkflowPessimisticLocking>true</useWorkflowPessimisticLocking>
        ...
    </transactionalDocument>
</dictionaryEntry>

The Pessimistic Locking mechanism for Workflow processes has lock creation and lock releasing points that exist in a document's post processor methods. Specifically the method doActionTaken(ActionTakenEventVO) in the DocumentBase class is used to create locks while the method afterWorkflowEngineProcess(boolean) in the same class is used to release locks. If a document overrides either of these methods or does not use the standard KualiPostProcessor implementation, the client will need to use the DocumentBase methods code in whatever method they implement if they would like Pessimistic Locking for Workflow.

The default owner of a Pessimistic Lock created for a Workflow process is the Rice System User. To change that a client can implement a custom Document Authorizer class and override the method getWorkflowPessimisticLockOwnerUser(). This method is used to get the lock owner for lock creation but also will be used to release the lock at the conclusion of the Workflow process. If a non-static user will be used a client may need to override the method releaseWorkflowPessimisticLocking(Document) to handle special cases.

Acegi handles the security layer for KSB. Acegi uses remote method invocation to hold the application's security context and to propagate this object through to the service layer.

For client applications to consume secured services hosted from a standalone Rice server, the implementer must generate a keystore in KSB. KSB security relies on the creation of a keystore using the JVM keytool.

Figure 7.1. Create Keystore

To create a new Client Keystore file, complete all three fields and click the create button that is just below the fields:

Figure 7.2. Create Keystore: File Section

The Desired Alias (name for the new keystore you are creating) must be unique among your keystores. KSB automatically displays a list of existing Keystore entries for your reference below the Create new Client Keystore file table. The data in this list can be sorted in ascending or descending order by clicking the column heading for any column except Actions.

Figure 7.3. Create Keystore: Existing Keystore Section

There are several security types you can use to propagate the security context object:

The CredentialsSource is an interface that helps obtain security credentials. It encapsulates the actual source of credentials. The two ways to obtain the source are:

<bean id="ksbConfigurer" class="org.kuali.rice.ksb.messaging.config.KSBConfigurer">
    <!-- Other properties removed -->
    <property name="services">
        <list>
            <bean class="org.kuali.rice.ksb.api.bus.support.SoapServiceDefinition">
                <property name="service">
                    <ref bean="soapService" />
                </property>
                <property name="localServiceName" value="soapLocalName"/>
                <property name="serviceNameSpaceURI" value="soapNameSpace"/>
                <property name="serviceInterface" value="org.kuali.ksb.examples.SOAPEchoService"/>
                <property name="priority" value="3"/>
                <property name="retryAttempts" value="1" />
                <property name="busSecurity" value="false"></property>
    
                <!-- Valid Values: CAS, KERBEROS -->
                <property name="credentialsType" value="CAS"/>
            </bean>
            <bean class="org.kuali.rice.ksb.api.bus.support.JavaServiceDefinition">
                <property name="service" ref="echoService"></property>
                <property name="localServiceName" value="javaLocalName" />
                <property name="serviceNameSpaceURI" value="javaNameSpace"/>
                <property name="serviceInterface" value="org.kuali.ksb.examples.EchoService"/>
                <property name="priority" value="5" />
                <property name="retryAttempts" value="1" />
                <property name="busSecurity" value="true" />

                <!-- Valid Values: CAS, KERBEROS -->
                <property name="credentialsType" value="CAS"/>
            </bean>
            <!-- Other services removed -->
        </list>
    </property>
</bean>

<bean id="customCredentialsSourceFactory" class="edu.myinstituition.myapp.security.credentials.CredentialsSourceFactory" />

<bean id="coreConfigurer" class="org.kuali.rice.core.impl.config.module.CoreConfigurer">
    <!-- Other properties removed -->
    <property name="credentialsSourceFactory" ref="customCredentialsSourceFactory">
</bean>

The BasicAuthenticationService allows services published on the KSB to be accessed securely with basic authentication. As an example, here is how the Workflow Document Actions Service could be exposed as a service with basic authentication.

As of the 2.0 version of Rice, the ServiceRegistry is now itself a service. In order to bring the registry online for the client application, the application needs to configure a URL similar to the following:

<param name="rice.ksb.registry.serviceUrl">http://localhost:8080/kr-dev/remoting/serviceRegistrySoap</param>

Currently, this connector is only configured to understand a SOAP interface to the service registry which is secured by digital signatures. This is the only type of interface to the registry that the standalone server currently publishes. Additionally, only a single URL to the registry can be configured at the current time. If someone wants to do load balancing amongst potential registry endpoints, then a hardware or software load balancer could be configured to do this.

The Kuali Service Bus (KSB) is installed as a Kuali Rice (Rice) Module using Spring. Here is an example XML snippet showing how to configure Rice and KSB using Spring:

<beans>
  ...
  <bean id="coreConfigurer" class="org.kuali.rice.core.impl.config.module.CoreConfigurer">
    <property name="dataSource" ref="riceDataSource${connection.pool.impl}" />
    <property name="nonTransactionalDataSource" ref="riceNonTransactionalDataSource" />
    <property name="transactionManager" ref="transactionManager${connection.pool.impl}" />
    <property name="userTransaction" ref="jtaUserTransaction" />
  </bean>

  <bean id="ksbConfigurer" class="org.kuali.rice.ksb.messaging.config.KSBConfigurer"/>
</beans>

The KSBTestHarnessSpring.xml located in the project folder under /ksb/src/test/resources/ is a good starting place to explore KSB configuration in depth. The first thing the file does is use a PropertyPlaceholderConfigurer to bring tokens into the Spring file for runtime configuration. The source of the tokens is the xml file: ksb-test-config.xml located in the /ksb/src/test/resources/META-INF directory.

<bean id="config" class="org.kuali.rice.core.config.spring.ConfigFactoryBean">
    <property name="configLocations">
        <list>
            <value>classpath:META-INF/ksb-test-config.xml</value>
        </list>
    </property>
</bean>


<bean class="org.springframework.beans.factory.config.MethodInvokingFactoryBean">
    <property name="staticMethod" value="org.kuali.rice.core.impl.config.property.ConfigInitializer.initialize"/>
    <property name="arguments">
        <list>
            <ref bean="config"/>
        </list>
    </property>
</bean>


<bean class="org.springframework.beans.factory.config.PropertyPlaceholderConfigurer">
    <property name="properties" value="#{config.getProperties()}" />
</bean>

As mentioned above, this allows tokens to be used in the Spring file. If you are not familiar with tokens, they look like this in the Spring file: ${datasource.pool.maxSize}

Let's take a look at the ksb-test-config.xml file:

<config>
    <param name="config.location">classpath:META-INF/common-derby-connection-config.xml</param>
    <param name="config.location">classpath:META-INF/common-config-test-locations.xml</param>
    <param name="client1.location">/var/lib/jenkins/workspace/rice-2.3-site-deploy/src/test/clients/TestClient1</param>
    <param name="client2.location">/var/lib/jenkins/workspace/rice-2.3-site-deploy/src/test/clients/TestClient2</param>
    <param name="ksb.client1.port">9913</param>
    <param name="ksb.client2.port">9914</param>
    <param name="ksb.testharness.port">9915</param>
    <param name="threadPool.size">1</param>
    <param name="threadPool.fetchFrequency">3000</param>
    <param name="bus.refresh.rate">3000</param>
    <param name="bam.enabled">true</param>
    <param name="transaction.timeout">3600</param>
    <param name="keystore.alias">rice<param>
    <param name="keystore.password">keystorepass</param>
    <param name="keystore.file">/var/lib/jenkins/workspace/rice-2.3-site-deploy/src/test/resources/keystore/ricekeystore</param>
    <param name="keystore.location">/var/lib/jenkins/workspace/rice-2.3-site-deploy/src/test/resources/keystore/ricekeystore</param>
    <param name="use.clearDatabaseLifecycle">true</param>
    <param name="use.sqlDataLoaderLifecycle">true</param>
    <!-- bus messaging props -->
    <param name="message.delivery">synchronous</param>
    <param name="message.persistence">true</param>
    <param name="useQuartzDatabase">false</param>
    <param name="config.location">${additional.config.locations}</param>
    <param name="config.location">${alt.config.location}</param>
</config>

This is an XML file for configuring key value pairs. When used in conjunction with Spring tokenization and the PropertyPlaceHolderConfigurer bean, the parameter name must be equal to the key value in the Spring file so that the properties propagate successfully.

When doing persistent messaging it is best practice to use JTA as your transaction manager. This ensures that the messages you are sending are synchronized with the current executed transaction in your application. It also allows message persistence to be put in a different database than the application's logic if needed. Currently, KSBTestHarnessSpring.xml uses JOTM to configure JTA without an application server. Bitronix is another JTA product that could be used in Rice and you could consider using it instead of JOTM. Below is the bean definition for JOTM that you can find in Spring:

<bean id="jotm" class="org.springframework.transaction.jta.JotmFactoryBean">
    <property name="defaultTimeout" value="${transaction.timeout}"/>

</bean>
<bean id="dataSource" class="org.kuali.rice.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.maxSize}" />
    <property name="minSize" value="${datasource.pool.minSize}" />
    <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>

Bittronix's configuration is similar. Datasources for both are set up in org.kuali.rice.core.RiceDataSourceSpringBeans.xml. If using JOTM, use the Rice XAPoolDataSource class as your data source because it addresses some bugs in the StandardXAPoolDataSource, which extends from this class.

Next, you must inject the JOTM into the RiceConfigurer:

<bean id="rice" class="org.kuali.rice.core.impl.config.module.CoreConfigurer">
    <property name="dataSource" ref="dataSource" />
    <property name="transactionManager" ref="jotm" />
    <property name="userTransaction" ref="jotm" />  
<...more.../>

Configuring JTA from an appserver is no different, except the TransactionManager and UserTransaction are going to be fetched using a JNDI FactoryBean from Spring.

You can configure KSB by injecting a PlatformTransactionManager into the KSBConfigurer.

This is a good option if you are an OJB shop and you want to continue using your current setup without introducing JTA into your stack. Normally, when a JTA transaction is found, the message is not sent until the transaction commits. In this case, the message is sent immediately.

Let's take a look at the KSBTestHarnessNoJtaSpring.xml file. Instead of JTA, the following transaction and DataSource configuration is declared:

<bean id="ojbConfigurer" class="org.springmodules.orm.ojb.support.LocalOjbConfigurer" />


<bean id="transactionManager" class="org.springmodules.orm.ojb.PersistenceBrokerTransactionManager">
    <property name="jcdAlias" value="dataSource" />
</bean>


<bean id="dataSource" class="org.springframework.jdbc.datasource.DriverManagerDataSource">
    <property name="driverClassName">
        <value>${datasource.driver.name}</value>
    </property>
    <property name="url">
        <value>${datasource.url}</value>
    </property>
    <property name="username">
        <value>${datasource.username}</value>
    </property>
    <property name="password">
        <value>${datasource.password}</value>
    </property>
</bean>

The RiceNoJtaOJB.properties file needs to include the Rice connection factory property value:

ConnectionFactoryClass=org.kuali.rice.core.framework.persistence.ojb.RiceDataSourceConnectionFactory

Often, the DataSource is pulled from JNDI using a Spring FactoryBean. Next, we inject the DataSource and transactionManager (now a Spring PlatformTransactionManager).

<bean id="rice" class="org.kuali.rice.core.impl.config.module.CoreConfigurer">
    <property name="dataSource" ref="dataSource" />
    <property name="nonTransactionalDataSource" ref="dataSource" />
    ...
</bean


<bean id="ksbConfigurer" class="org.kuali.rice.ksb.messaging.config.KSBConfigurer">
    <property name="platformTransactionManager" ref="transactionManager" />
    <... more .../>
</bean>

Notice that the transactionManager is injected into the KSBConfigurer directly. This is because only KSB, and not Rice, supports this type of configuration. The DataSource is injected normally. When doing this, the OJB setup is entirely in the hands of the client application. That doesn't mean anything more than providing an OJB.properties object at the root of the classpath so OJB can load itself. KSB will automatically register its mappings with OJB, so they don't need to be included in the repository.xml file.

To allow external bus clients to invoke services on the bus-connected node, you must configure the KSBDispatcherServlet in the web applications web.xml file. For example:

<servlet>
    <servlet-name>remoting</servlet-name>
    <servlet-class>org.kuali.rice.ksb.messaging.servlet.KSBDispatcherServlet</servlet-class>
    <load-on-startup>1</load-on-startup>

</servlet>

<servlet-mapping>
    <servlet-name>remoting</servlet-name>
    <url-pattern>/remoting/*</url-pattern>
</servlet-mapping>

This allows bus-exposed services to be accessed at a URL like http://yourlocalip:8080/myapp/remoting/[KSB:service name]. Notice how this URL corresponds to the configured serviceServletUrl property on the KSBConfigurer.

The service bus leverages the Rice configuration system for its configuration. Here is a comprehensive set of configuration parameters that you can use to configure the Kuali Service Bus:

In addition to the configuration parameters that you can specify using the Rice configuration system, the KSBConfigurer bean itself has some properties that can be injected in order to configure it:

The application needs to do one more thing to begin publishing services to the bus: Configure the KSBConfigurer object. This can be done using Spring or programmatically. We'll use Spring because it's the easiest way to get things configured:

<bean id="jotm" class="org.springframework.transaction.jta.JotmFactoryBean">
    <property name="defaultTimeout" value="${transaction.timeout}"/>
</bean>



<bean id="dataSource" class=" org.kuali.rice.core.database.XAPoolDataSource ">
    <property name="transactionManager" ref="jotm"/>
    <property name="driverClassName" value="oracle.jdbc.driver.OracleDriver"/>
    <property name="maxSize" value="25"/>
    <property name="minSize" value="2"/>
    <property name="maxWait" value="5000"/>
    <property name="validationQuery" value="select 1 from dual"/>
    <property name="url" value="jdbc:oracle:thin:@LOCALHOST:1521:XE"/>
    <property name="username" value="myapp"/>
    <property name="password" value="password"/>
</bean>


<bean id="nonTransactionalDataSource" class="org.apache.commons.dbcp.BasicDataSource" destroy-method="close">
        <property name="driverClassName" value="oracle.jdbc.driver.OracleDriver"/>
        <property name="url" value="jdbc:oracle:thin:@LOCALHOST:1521:XE"/>
        <property name="maxActive" value="50"/>
        <property name="minIdle" value="7"/>
        <property name="initialSize" value="7"/>
        <property name="validationQuery" value="select 1 from dual"/>
        <property name="username" value="myapp"/>
        <property name="password" value="password"/>
        <property name="accessToUnderlyingConnectionAllowed" value="true"/>
</bean>

<bean id="coreConfigurer" class="org.kuali.rice.core.impl.config.module.CoreConfigurer">
    <property name="dataSource" ref="datasource" />
    <property name="nonTransactionalDataSource" ref="nonTransactionalDataSource" />
    <property name="transactionManager" ref="jotm" />
    <property name="userTransaction" ref="jotm" />
</bean>

<bean id="ksbConfigurer" class="org.kuali.rice.ksb.messaging.config.KSBConfigurer"/>

The application is now ready to deploy services to the bus. Let's take a quick look at the Spring file above and what's going on there: The following configures JOTM, which is currently required to run KSB.

<bean id="jotm" class="org.springframework.transaction.jta.JotmFactoryBean" />

Next, we configure the XAPoolDataSource and the non transactional BasicDataSource. This is pretty much standard data source configuration stuff. The XAPoolDataSource is configured through Spring and not JNDI so it can take advantage of JTOM. Servlet containers, which don't support JTA, require this configuration step so the datasource will use JTA.

<bean id="dataSource" class=" org.kuali.rice.core.database.XAPoolDataSource ">
    <property name="transactionManager" ref="jotm"/>
    <property name="driverClassName" value="oracle.jdbc.driver.OracleDriver"/>
    <property name="url" value="jdbc:oracle:thin:@LOCALHOST:1521:XE"/>
    <property name="maxSize" value="25"/>
    <property name="minSize" value="2"/>
    <property name="maxWait" value="5000"/>
    <property name="validationQuery" value="select 1 from dual"/>
    <property name="username" value="myapp"/>
    <property name="password" value="password"/>
</bean>

<bean id="nonTransactionalDataSource" class="org.apache.commons.dbcp.BasicDataSource" destroy-method="close">
    <property name="driverClassName" value="oracle.jdbc.driver.OracleDriver"/>
    <property name="url" value="jdbc:oracle:thin:@LOCALHOST:1521:XE"/>
    <property name="maxActive" value="50"/>
    <property name="minIdle" value="7"/>
    <property name="initialSize" value="7"/>
    <property name="validationQuery" value="select 1 from dual"/>
    <property name="username" value="myapp"/>
    <property name="password" value="password"/>
    <property name="accessToUnderlyingConnectionAllowed" value="true"/>
</bean>        

Next, we configure the bus:

<bean id="rice" class="org.kuali.rice.core.config.CoreConfigurer">
    <property name="dataSource" ref="dataSource" />
    <property name="nonTransactionalDataSource" ref="nonTransactionalDataSource" />
    <property name="transactionManager" ref="jotm" />
    <property name="userTransaction" ref="jotm" />
</bean>

<bean id="ksbConfigurer" class="org.kuali.rice.ksb.messaging.config.KSBConfigurer">
    <property name="registryDataSource" ref="dataSource" />
    <property name="bamDataSource" ref="dataSource" />
    <property name="messageDataSource" ref="dataSource" />
    <property name="nonTransactionalMessageDataSource" ref="nonTransactionalDataSource" />
</bean>

We are injecting JOTM, and the datasources. The injection of the KSBConfigurer class into the ksbConfigurer property tells this instance of Rice to start the Service Bus. The final necessary step is making sure the configuration parameter 'application.id' is set properly to some value that will identify all services deployed from this node as a member of this node.

At this point, the application is configured to use the bus, both for publishing services and to send messages to services. Usually, applications will publish services on the bus using the KSBConfigurer or the SoapServiceExporter classes. See Acquiring and invoking services for more detail.

The Kuali Service Bus (KSB) uses Quartz to schedule delayed tasks, including retry attempts for messages that cannot be sent the first time. By default, KSB uses an embedded quartz scheduler that can be configured by passing parameters starting with "ksb.org.quartz." into the Rice configuration.

If the application is already running a quartz scheduler, you can inject a custom quartz scheduler using code like this:

<bean class="org.kuali.rice.ksb.messaging.config.KSBConfigurer">
    ...
    <property name="exceptionMessagingScheduler">
        <bean class="org.springframework.scheduling.quartz.SchedulerFactoryBean">
            ...
        </bean>
    </property>
</bean>

When you do this, KSB will not create an embedded scheduler but will instead use the one provided.

In the examples below, notice that the client code is unaware of the protocol with which the underlying service is deployed. Given a connector for a given protocol and a compatible service definition, you could move a service to different protocols as access needs change without affecting dependent client code.

The easiest way to call a service is to grab it and invoke it directly. This uses a direct request/response pattern and what you see is what you get. You will wait for the processing the call takes on the other side plus the cost of the remote connection time. Any exceptions thrown will come across the wire in a protocol-acceptable way.

This code acquires a SOAP-based service and calls it:

QName serviceName = new QName("testNameSpace", "soap-repeatTopic");

SOAPService soapService = (SOAPService) GlobalResourceLoader.getService(serviceName);
soapService.doTheThing("hello");

The SOAPService interface needs to be in the client classpath and bindable to the WSDL. The easiest way to achieve this in Java is to create a bean that is exported as a SOAP service. This is the server-side service declaration in a Spring file:

<bean id="ksbConfigurer" class="org.kuali.rice.ksb.messaging.config.KSBConfigurer">
  ...
  <property name="services">
    <list>
        <bean class="org.kuali.rice.ksb.api.bus.support.SoapServiceDefinition">
            <property name="service">
              <ref bean="soapService" />
            </property>
            <property name="localServiceName" value="soap-repeatTopic" />
            <property name="serviceNameSpaceURI" value="testNameSpace" />
            <property name="priority" value="3" />
            <property name="queue" value="false" />
            <property name="retryAttempts" value="1" />
        </bean>
        ...
    </list>
  </property>
</bean> 

This declaration exposes the bean soapService on the bus as a SOAP available service. The Web Service Definition Language is available at the serviceServletUrl + serviceNameSpaceURI + localServiceName + ?wsdl.

This next code snippet acquires and calls a Java base service:

EchoService echoService = (EchoService)GlobalResourceLoader.getService(new QName("TestCl1", "echoService"));
String echoValue = "echoValue";
String result = echoService.echo(echoValue);

Again, the interface is all that is required to make the call. This is the server-side service declaration that deploys a bean using Spring's HttpInvoker as the underlying transport:

<bean id="ksbConfigurer" class="org.kuali.rice.ksb.messaging.config.KSBConfigurer">
  ...
  <property name="services">
    <list>
        <bean class="org.kuali.rice.ksb.api.bus.support.SoapServiceDefinition">
            <property name="service" ref="echoService" />
            <property name="serviceInterface" value="org.kuali.rice.ksb.messaging.remotedservices.EchoService" />
            <property name="localServiceName" value="soap-echoService" />
            <property name="busSecurity" value="false"></property>
        </bean>
        ...
    </list>
  </property>
</bean> 

Below is a description of each property on the ServiceDefinition (JavaServiceDefinition and SOAPServiceDefinition):

To make a call to a service through messaging, acquire the service by its name using the MessageHelper:

QName serviceName = new QName("testAppsSharedQueue", "sharedQueue");

KEWSampleJavaService testJavaAsyncService = (KEWSampleJavaService) KsbApiServiceLocator.getMessageHelper().getServiceAsynchronously(serviceName);

At this point, the testJavaAsyncService can be called like a normal JavaBean:

testJavaAsyncService.invoke(new ClientAppServiceSharedPayloadObj("message content", false));

Because this is a queue, a single message is sent to one of the beans bound to the service name new QName("testAppsSharedQueue", "sharedQueue"). That 'message' is the call 'invoke' and it takes a ClientAppServiceSharedPayloadObj. Typically, messaging is done asynchronously. Messages are sent when the currently running JTA transaction is committed - that is, the messaging layer automatically synchronizes with the current transaction. So, using JTA, even though the above is coded in line with code, invocation is normally delayed until the transaction surrounding the logic at runtime is committed.

When not using JTA, the message is sent asynchronously (by a different thread of execution), but it's sent ASAP.

To review, the requirements to use a service that is exposed to the bus on a different machine are:

To complete the example: Below is the Spring configuration used to expose this service to the bus. This is taken from the file TestClient1SpringBeans.xml:

<!-- bean declaration -->
<bean id="sharedQueue" class=" org.kuali.rice.ksb.testclient1.ClientApp1SharedQueue" />

<bean id="ksbConfigurer" class="org.kuali.rice.ksb.messaging.config.KSBConfigurer">
  ...
  <property name="services">
    <list>
        <bean class=" org.kuali.rice.ksb.messaging.JavaServiceDefinition">
            <property name="service" ref="sharedQueue" />
            <property name="localServiceName" value="sharedQueue" />
            <property name="serviceNameSpaceURI" value="testAppsSharedQueue" />
        </bean>
        <... more .../>
    </list>
  </property>
</bean> 

This is located in the Spring file of the application exposing the service (in other words, the location in which the actual invocation will occur). The client does not need a Spring configuration to invoke the service.

There are two messaging call paradigms, called Topics and Queues. When any number of services is declared a Topic, then those services are invoked at least once or multiple times. If any number of services is declared a Queue, then one and only one service name will be invoked.

You can use Callback objects to get responses from service calls made using messaging. Acquiring a service for use with a Callback:

QName serviceName = new QName("TestCl1", "testXmlAsyncService");
SimpleCallback callback = new SimpleCallback();
KSBXMLService testXmlAsyncService = (KSBXMLService) KsbApiServiceLocator.getMessageHelper().getServiceAsynchronously(serviceName, callback);

testXmlAsyncService.invoke("message content");

When the service is invoked asynchronously, the AsynchronousCallback object's (the SimpleCallback class above) callback method is called.

When message persistence is turned on, this object is serialized with any method call made through the messaging API. Take into consideration that this object (and the result of a method call) may survive machine restart and therefore it's recommended that you NOT depend on certain transient in-memory resources.

Failover works the same whether making direct service calls or using messaging.

Services exported to the bus have automatic failover from the client's perspective. For example, if service A is deployed on machines 1 and 2 and a client happens to get a proxy that points to machine 1 but machine 1 crashes, the KSB will automatically detect that the exception is a result of some network issue and direct the call to machine 2. KSB then removes machine 1 from the registry so new clients to the bus don't try to acquire the service. When machine 1 returns to the network it will register itself with the service registry and therefore the bus.

When a message calls a service, the failover rules determine which service KSB assigns (topic or queue) to the message.

Because queues require only one call between all beans bound to the queue, if a single call to a queue fails, failover to the next bean occurs. If successful, the call is done. If it is not successful, it continues until a suitable bean is found. If none is found, the message is marked for retry later. Eventually, the message either goes to KSB exception messaging or successfully completes.

If a machine in a topic is unavailable, a failed call to that machine will continue to be retried until that call is successful or that call goes into KSB exception messaging.

When any number of services is bound to a queue and a method is invoked, one and only one service gets the invocation.

When any number of services is bound to a topic and a method is invoked, all services are invoked AT LEAST once or multiple times.

org.kuali.rice.ksb.messaging.MessageFetcher is a Runnable that needs to be configured by the client application to retrieve stored messages from the database that weren't processed when the node went down. This can happen for many reasons. The machine can be under load and just crash.

When message persistence is enabled, a service that fails or throws an Exception stores preprocessed messages in the database until they can be resent. This makes certain that a crash or emergency restart of your machine will not result in message loss.

The KSB does not automatically fetch all these messages and attempt to invoke them when it starts, because often the KSB is started when the services the messages are bound for are not yet started. For now, you need to decide when to call the run method on the MessageFetcher. Because it's a Runnable, you could also put the MessageFetcher in the KSBThreadPool that is available on the KSBServiceLocator. You could wrap it in a TimerTask, etc. All that is required is this:

new MessageFetcher((Integer) null).run()

Unfortunately, the cast to Integer is required. The MessageFetcher also has a constructor that takes a long variable as a parameter. This can be used to pull any message in the message store and put it in memory for invocation. Integer is a fetch size; null means all.

A service can be exposed by explicitly registering it with the KSBConfigurer module, services property:

<bean class="org.kuali.rice.ksb.messaging.config.KSBConfigurer">
    <property name="serviceServletUrl" value="${base url}/MYAPP/remoting/" />
    ...
    <property name="services">
      <list>
          <bean class="org.kuali.rice.ksb.api.bus.support.SoapServiceDefinition">
              <property name="service">
                  <ref bean="mySoapService" />
              </property>
              <property name="serviceInterface"><value>org.myapp.services.MySOAPService</value></property>
              <property name="localServiceName" value="myExposedSoapService" />
          </bean>
          <bean class="org.kuali.rice.ksb.api.bus.support.JavaServiceDefinition">
              <property name="service">
                  <ref bean="myJavaService" />
              </property>
              <property name="serviceInterface">
                  <value>org.myapp.services.MyJavaService</value></property>
              <property name="localServiceName" value="myExposedJavaService" />
          </bean>

You can also publish Services in any context using the ServiceBusExporter (or PropertyConditionalServiceBusExporter) bean. Note that KSBConfigurer must also be defined in your RiceConfigurer.

<bean id="myapp.serviceBus"
        class="org.kuali.rice.core.framework.resourceloader.GlobalResourceLoaderServiceFactoryBean">
    <property name="serviceName" value="rice.ksb.serviceBus"/>
</bean>

<bean id="myAppServiceExporter"
        class="org.kuali.rice.ksb.api.bus.support.ServiceBusExporter"
        abstract="true">
    <property name="serviceBus" ref="myapp.serviceBus"/>
</bean>

<bean id="myJavaService.exporter" parent="myAppServiceExporter">
    <property name="serviceDefinition">
        <bean class="org.kuali.rice.ksb.api.bus.support.JavaServiceDefinition">
            <property name="service">
                <ref bean="myJavaService" />
            </property>
            <property name="serviceInterface">
                <value>org.myapp.services.MyJavaService</value>
            </property>
            <property name="localServiceName" value="myExposedJavaService" />
        </bean>
    </property>
</bean>

<bean id="mySoapService.exporter" parent="myAppServiceExporter">
    <property name="serviceDefinition">
        <bean class="org.kuali.rice.ksb.api.bus.support.SoapServiceDefinition">
            <property name="service">
                <ref bean="mySoapService" />
            </property>
            <property name="serviceInterface">
                <value>org.myapp.services.MySOAPService</value>
            </property>
            <property name="localServiceName" value="myExposedSoapService" />
        </bean>
    </property>

</bean>

The term "Callback Service" refers to services that client applications write and configure and which are used by various modules of Rice including KIM, KEW, and KRMS. Because of the naming convention on these, they are often referred to as "Type Services". These include:

These are typically called back into from the Rice Standalone Server when needing information for rendering of various components in the server-side user interface. Additionally, in some cases they can also be used to provide custom processing hooks for different components of the various Kuali Rice frameworks.

<bean id="sampleAppPeopleFlowTypeService.exporter"
      class="org.kuali.rice.ksb.api.bus.support.CallbackServiceExporter"
      p:serviceBus-ref="rice.ksb.serviceBus"
      p:callbackService-ref="sampleAppPeopleFlowTypeService"
      p:serviceNameSpaceURI="http://rice.kuali.org/sample-app"
      p:localServiceName="sampleAppPeopleFlowTypeService"
      p:serviceInterface="org.kuali.rice.kew.framework.peopleflow.PeopleFlowTypeService"/>

ServiceDefinitions define how the service is published to the KSB. Currently KSB supports three types of services: Java RPC (via serialization over HTTP), SOAP, and JMS.

ServiceNameSpaceURI is the same as the Message Entity that composes the qualified name under which the service is exposed. When omitted, this namespace defaults to the message entity configured for Rice (e.g., in the RiceConfigurer), thereby qualifying the local name. Note: Although this implicit qualification occurs during export, you must always specify an explicit message entity when acquiring a resource, for example:

GlobalResourceLoader.getService(new QName("MYAPP", "myExposedSoapService"))

We show how you can "import" Rice services into the client Spring application context in Configuring KSB Client in Spring. Using this technique, you can also publish Rice services on the KSB:

<!-- import a Rice service from the ResourceLoader stack -->
<bean id="myapp.aRiceService" class="org.kuali.rice.core.framework.resourceloader.GlobalResourceLoaderServiceFactoryBean">
    <property name="serviceName" value="aRiceService"/>
</bean


<!-- if Rice does not publish this service on the bus, one can explicitly publish it -->
<bean id="myAppServiceExporter"
        class="org.kuali.rice.ksb.api.bus.support.ServiceBusExporter"
        abstract="true">
    <property name="serviceBus" ref="myapp.serviceBus"/>
</bean>

<bean id="myJavaService.exporter" parent="myAppServiceExporter">
    <property name="serviceDefinition">
        <bean class="org.kuali.rice.ksb.api.bus.support.JavaServiceDefinition">
            <property name="service">
                <ref bean="aRiceService" />
            </property>
            <property name="serviceInterface" value="org.kuali.rice...SomeInterface" />
            <property name="localServiceName" value="aPublishedRiceService" />
        </bean>
    </property>
</bean>

Remote service proxies obtained through the resource loader stack using getService(QName) (ultimately through the ServiceBus) are inherently synchronous. In the presence of multiple service registrations, the ServiceBus will choose one at random.

When invoking services asynchronously through the MessageHelper, an asynchronous service call proxy will be constructed with all available service definitions. The MessageServiceInvoker is called to invoke each service. If the service is defined as a queue service, then the ServiceBus will be consulted in a similar fashion to determine a single service to call. After the first queue service invocation the MessageServiceInvoker will return.

The simplest way to invoke a topic service is using the MessageHelper functions to invoke the service asynchronously. As described above for an asynchronous queue invocation, an asynchronous service call proxy will be constructed with the list of all of the services registered as a topic under the given name. Each of these services will be independently obtained and invoked by the MessageServiceInvoker.

Invoking a topic synchronously, however, requires use of a synchronous service call proxy to aggregate all of the topic's services. This functionality is not directly available via the ServiceBus API because the ServiceBus acts as a facade for direct service invocation.

To invoke a topic synchronously, you can construct a SynchronousServiceCallProxy using SynchronousServiceCallProxy.createInstance, passing the list of Endpoint obtained using ServiceBus.getEndpoints(QName). This is done, for example, by MessageHelperImpl when the bus has been forced into synchronous mode via the message.delivery config param.

The synchronous service call proxy is the same as the asynchronous service call proxy, except that it does not queue up the invocation, it will invoke it blockingly. The same queue/topic distinctions described above apply when you invoke a topic synchronously. Under the normal queue situation, use of the synchronous service call proxy is not necessary because, as mentioned above, remote services obtained through the ServiceBus are naturally synchronous. You can see this in the example below:

List<Endpoint> servicesToProxy = KsbApiServiceLocator.getServiceBus().getEndpoints(qname);

SynchronousServiceCallProxy sscp = return SynchronousServiceCallProxy.createInstance(servicesToProxy, callback, context, value1, value2);

In addition to the configuration parameters available in the KRice configuration system, the KSBConfigurer bean has some properties that can be injected to configure it:

To expose a simple JAX-RS annotated service on the bus, you can follow this recipe for your spring configuration (which comes from the Rice unit tests):

<!-- The service implementation you want to expose -->

<bean id="baseballCardCollectionService" class="org.kuali.rice.ksb.testclient1.BaseballCardCollectionServiceImpl"/>


<!-- The service definition which tells the KSB to expose our RESTful service -->
<bean class="org.kuali.rice.ksb.messaging.RESTServiceDefinition">
    <property name="serviceNameSpaceURI" value="test" />


    <!-- as noted earlier, the servicePath property of RESTServiceDefinition can't be set here  -->


    <!-- The service to expose.  Refers to the bean above -->
    <property name="service" ref="baseballCardCollectionService" />


    <!-- The "Resource class", the class with the JAX-RS annotations on it.  Could be the same as the  -->
    <!-- service implementation, or could be different, e.g. an interface or superclass    -->
  
    <property name="resourceClass" 
value="org.kuali.rice.ksb.messaging.remotedservices.BaseballCardCollectionService" />


    <!-- the name of the service, which will be part of the RESTful URLs used to access it -->
    <property name="localServiceName" value="baseballCardCollectionService" />
</bean>

The following java interface uses JAX-RS annotations to specify its RESTful interface:

// … eliding package and imports

@Path("/")
public interface BaseballCardCollectionService {
    @GET
    public List<BaseballCard> getAll();


    /**
      * gets a card by it's (arbitrary) identifier
      */
    @GET
    @Path("/BaseballCard/id/{id}")
    public BaseballCard get(@PathParam("id") Integer id);
    /**
      * gets all the cards in the collection with the given player name
      */
    @GET
    @Path("/BaseballCard/playerName/{playerName}")
    public List<BaseballCard> get(@PathParam("playerName") String playerName);


    /**
      * Add a card to the collection.  This is a non-idempotent method
      * (because you can add more than one of the same card), so we'll use @POST
      * @return the (arbitrary) numerical identifier assigned to this card by the service
      */
    @POST
    @Path("/BaseballCard")
    public Integer add(BaseballCard card);


    /**
      * update the card for the given identifier.  This will replace the card that was previously
      * associated with that identifier.
      */
    @PUT
    @Path("/BaseballCard/id/{id}")
    @Consumes("application/xml")
    public void update(@PathParam("id") Integer id, BaseballCard card);


    /**
      * delete the card with the given identifier.
      */
    @DELETE
    @Path("/BaseballCard/id/{id}")
    public void delete(@PathParam("id") Integer id);

    /**
      * This method lacks JAX-RS annotations
      */
    public void unannotatedMethod();
}

Acquisition and use of this service over the KSB looks just like that of any other KSB service. In the synchronous case:

BaseballCardCollectionService baseballCardCollection = (BaseballCardCollectionService) GlobalResourceLoader.getService(new QName("test", "baseballCardCollectionService");
);


List<BaseballCard> allMyMickeyMantles = baseballCardCollection.get("Mickey Mantle");
// baseballCardCollection.<other service method>(...)
// etc

It is also possible to aggregate multiple Rice service implementations into a single RESTful service where requests to different sub-paths off of the base service URL can be handled by different underlying services. This may be desirable to expose a RESTful service that is more complex than could be cleanly factored into a single java service interface.

The configuration for a composite RESTfull service looks a little bit different, and as might be expected given the one-to-many mapping from RESTful service to java services, there are some caveats to using that service over the KSB. Here is a simple example of a composite service definition (which also comes from the Rice unit tests):

<bean class="org.kuali.rice.ksb.messaging.RESTServiceDefinition">
    <property name="serviceNameSpaceURI" value="test" />
    <property name="localServiceName" value="kms" />
    <property name="resources">
        <list>
            <ref bean="inboxResource"/>
            <ref bean="messageResource"/>
        </list>
    </property>
    <property name="servicePath" value="/" />
</bean>


<!-- the beans referenced above are just JAX-RS annotated Java services -->
<bean id="inboxResource" class="org.kuali.rice.ksb.testclient1.InboxResourceImpl">
    <!-- ... eliding bean properties ... -->
</bean>
<bean id="messageResource" class="org.kuali.rice.ksb.testclient1.MessageResourceImpl">
    <!-- ... eliding bean properties ... -->

</bean>

As you can see in the bean definition above, the service name is kms, so the base service url would by default (in a dev environment) be http://localhost:8080/kr-dev/remoting/kms/. Acquiring a composite service such as this one on the KSB will actually return you a org.kuali.rice.ksb.messaging.serviceconnectors.ResourceFacade, which allows you to get the individual java services in a couple of ways, as shown in the following simple example:

ResourceFacade kmsService =
 (ResourceFacade) GlobalResourceLoader.getService(
new QName(NAMESPACE, KMS_SERVICE));


// Get service by resource name (url path)
InboxResource inboxResource = kmsService.getResource("inbox");
// Get service by resource class
MessageResource messageResource = kmsService.getResource(MessageResource.class);

There are some properties on the RESTServiceDefinition object that let you do more advanced configuration: