View source for Stardust/Knowledge Base/API/ExamplesofAPIUsage/Initialization

== API Initialization  ==

==== Purpose  ====

Working with Stardust via the Java API always means working with Stardust's services. The commonly used ones areas 

*QueryService: It is used for any kind of information retrieval about processes, activites and their instances. 
*UserService: It is used for any kind of user-related operations like creating new user, granting roles and so on. 
*WorkflowService: Is is used for executing the process instances (starting, stopping, resuming and so on). 
*DocumentManagementService: Is is used for accessing a JCR repository. <br>

But there are also others like the DocumentService for special purposes. All these services are used in the same way: They need to be initialized in order to work with them.

==== Solution  ====

Working with the services is quite easy. Getting the service instances itself requires some setup. The initialization itself is done for you by Stardust. 

'''Requirements'''<br> 

Your client's carnot.properties has to be set up correctly. If you use the Stardust in EJB-mode you need another carnot.properties as if stardust is deployed in Spring mode. But this is another carnot.properties as your server (Stardust itself) uses. 

'''Client vs. Server'''<br> 

Stardust(exactly the carnot-engine) is the server. It (among others) creates the service objects we will use later. Its carnot.properties will be deployed in the Application Server/Container below WEB-INF/classes (or simmilar).<br>The client (the program you will write which will use the Stardust services) needs another carnot.properties. It is required to be on the classpath so it can be found during runtime. 

You can find your adequate carnot.properties in your Infinity installation directory: <br>'''EJB Mode'''<br> 

*&lt;INFINITY_HOME&gt;/work/default-ejb/etc/carnot.properties is a good starting point if you use Stardust in EJB mode.

Important configuration options are 

:*Client.ServiceFactory - default should be ok 
:*WorkflowService.JndiName - default should be ok 
:*AdministrationService.JndiName - default should be ok 
:*UserService.JndiName - default should be ok 
:*QueryService.JndiName - default should be ok 
:*JNDI.URL - Depends on your application server 
:*JNDI.InitialContextFactory - Depends on your application server

'''Spring Mode'''

&lt;INFINITY_HOME&gt;/work/default/etc/carnot.properties is a good starting point if you use Stardust in Spring mode.<br>

'''No Database-Settings'''<br>

If you get errors about missing AuditTrail.URL or similar you are on the wrong way. Your client will only use the services and doesn't need to know anything about the Audittrail database. 

'''WikiProgram.java'''
<source lang="java">
package com.sungard.wiki;

import ag.carnot.workflow.runtime.DocumentManagementService;
import ag.carnot.workflow.runtime.QueryService;
import ag.carnot.workflow.runtime.ServiceFactory;
import ag.carnot.workflow.runtime.ServiceFactoryLocator;
import ag.carnot.workflow.runtime.UserService;
import ag.carnot.workflow.runtime.WorkflowService;

public class WikiProgram {
	private static ServiceFactory serviceFactory;
	private static QueryService queryService;
	private static WorkflowService workflowService;
	private static UserService userService;
	private static DocumentManagementService documentService;

	public static void main(String[] unused) {
		try {
			init();

			// Do your stuff here

		} finally {
			uninit();
		}
	}
	static void init() {
		// Get the factory and provide login credentials
		serviceFactory = ServiceFactoryLocator.get("motu", "motu");
		// Get the service instances
		queryService = serviceFactory.getQueryService();
		workflowService = serviceFactory.getWorkflowService();
		userService = serviceFactory.getUserService();
		documentService = serviceFactory.getDocumentManagementService();
	}

	static void uninit() {
		if (serviceFactory != null) {
			// Release all resources
			serviceFactory.close();
		}
	}
}
</source>

In Above Example no need for the JNDI-Lookups, no PortableRemoteObject.narrow(). This code works with an EJB server and and Spring server. You just need to reconfigure your client's carnot.properties.

Please Note: Always remember to close() the SessionFactory to release resources.