using_Railo_in_Java - getrailo/railo GitHub Wiki

Table of Contents Using Railo in Java Adding Railo to your Java Project Using Railo from your Java code when your Java code was loaded by Railo when Railo does not load your Java code Using the Railo objects from Java Calling CFC Methods from Java calling method with no arguments calling method with ordered arguments calling method with named arguments Other Useful Methods of the PageContext class Get Railo Scopes Get/Set Variables Create CF Objects Decision Util Operations Util Casting Exceptions Util Evaluate Serialize

Using Railo in Java

while Railo allows you to do almost everything your web application will need to do by using CFML code, there may be times when you will need to use Railo from Java applications.

since Railo is written in Java, and is running inside a Java Virtual Machine (JVM), using Railo from your java applications is very easy.

Adding Railo to your Java Project

the first thing you will need to do is to add railo.jar to your classpath, so that you will have access to the classes and interfaces that Railo provides. if you are using an IDE like Eclipse or Netbeans, then you simply add the railo.jar library to your project.

once you added railo.jar to your project, you should have access to all of Railo's public classes and interfaces. in order to access them you will need to add the import statement to the top of your class file. be sure to add an import statement for each of the classes/interfaces that you plan to use in that class. you can review the Railo javadoc files at http://www.getrailo.org/javadoc/

Using Railo from your Java code

there are two cases in which you might want to use Railo from your Java code:

when your Java code is loaded into the JVM through Railo
in a standalone application detached from a Railo web app

when your Java code was loaded by Railo

the easiest way to use Railo from your Java code is when your Java code was loaded by Railo. this is a common case when, for example, your CFML code creates a Java object, and then that Java object creates Railo objects and calls CFC methods.

your interaction with Railo should start via an object that implements the railo.loader.engine.CFMLEngine interface (http://www.getrailo.org/javadoc/railo/loader/engine/CFMLEngine.html) and the railo.runtime.PageContext (http://www.getrailo.org/javadoc/railo/runtime/PageContext.html) object. since Railo loaded your Java code, and it will be running in that very same JVM, you can get a reference to a CFMLEngine object by calling the getInstance() static method of the railo.loader.engine.CFMLEngineFactory object.

import	railo.loader.engine.*;
...

public class MyClass {

	CFMLEngine	engine	= CFMLEngineFactory.getInstance();
	PageContext 	pc 	= engine.getThreadPageContext();
	...
}

in the following examples in this document "engine" will refer to a railo.loader.engine.CFMLEngine object, and "pc" will refer to a railo.runtime.PageContext object.

when Railo does not load your Java code

when you want to use Railo from Java in a detached environment, i.e. Railo does not load your Java code -- it is a little more complicated to access Railo, as you will have to create the CFMLEngine and the PageContext objects yourself.

due to the complexity involved this is beyond the scope of this document. please consult the code written for Railo CLI in Version 4.0 Alpha and see how it is used there:

https://github.com/getrailo/railo/blob/develop/railo-java/railo-loader/src/railo/cli/CLI.java and in the cli() method of CFMLEngineImpl (line 541 at the time of writing): https://github.com/getrailo/railo/blob/develop/railo-java/railo-core/src/railo/runtime/engine/CFMLEngineImpl.java#L541

Using the Railo objects from Java

once you have a reference to the CFMLEngine and the PageContext objects, you can easily interact with Railo from your code. here is an example on how to get / set Railo values from within your Java code:

// get a reference to the Application Scope:
Scope	appScope	=	pc.applicationScope();
	
// get a value from the Application Scope:
String	appName1	=	appScope.get( "ApplicationName" );

// you can also get the value from the PageContext directly:
String	appName2	= 	pc.getVariable( "Application.ApplicationName" );

if ( !appName1.equals( appName2 ) )
	throw new ApplicationException( "WTF?!@#" );

you can also set variables in a similar manner:

// this is the Java equivalent of <cfset Application.javaTime = getTickCount()>
pc.setVariable( "Application.javaTime", System.currentTimeMillis() );

then in your CFML code, you can use this value like so:

<cfoutput>The Tick Count set from Java was: #Application.javaTime#</cfoutput>

in the same way you can get a reference to other objects in the different scopes. for example, if in onApplicationStart() (of Application.cfc) your Railo code creates somewhere a component and sets a reference to it in Application.myCfc

<cffunction name="onApplicationStart">

	<cfset Application.myCfc = createObject( "component", "my.lib.Comp" )>
</cffunction>

then you can get a reference to it in Java like this:

Component cfc		= 	(Component) pc.getVariable( "Application.myCfc" );

if ( cfc != null ) {

	... do something with cfc ...
}

alternatively, if you want to create a new CFC in your Java code, you can use the PageContext's loadComponent method:

// this will cause Railo to search it's component mapping paths for my.lib.Comp and create a new component
Component cfc		= 	pc.loadComponent( "my.lib.Comp" );
	
// set it to a variable in the Application scope
pc.setVariable( "Application.myCfc", cfc );

Calling CFC Methods from Java

once you have a reference to a CFC you can invoke its methods by using the call() or callWithNamedValues() methods:

calling method with no arguments

// call the CFC's funcation getLastName with no args (empty array):
String lastName = (String) cfc.call( pc, "getLastName", new Object[0] );

calling method with ordered arguments

// execute the cfc with ordered arguments
cfc.call( pc, "setLastName", new Object[]{ "Smith" } );

calling method with named arguments

// execute the cfc with named arguments
Struct	args	=	engine.getCreationUtil().createStruct();
args.set( "name", "Smith" );
cfc.callWithNamedValues( pc, "setLastName", args );

Other Useful Methods of the PageContext class

Get Railo Scopes

Scope varialbesScope	= pc.variablesScope();

Scope requestScope	= pc.requestScope();

Scope sessionScope	= pc.sessionScope();

Scope applicationScope	= pc.applicationScope();

Get/Set Variables

// get variable by using its fully qualified name
String username = (String) pc.getVariable( "session.username" );

// set variable by using its fully qualified name
pc.setVariable( "session.username", "Susanne" );

// get variable from scope obtained earlier
String username = (String) sessionScope.get( "username" );

// set variable in scope obtained earlier
sessionScope.set( "username", "Susanne" );

(of course, as with your CFML code, you should only set values to shared objects in a synchronized manner)

Create CF Objects

// get a reference to the creation utility class
Creation	creationUtil		=	engine.getCreationUtil();

// create CF Array
railo.runtime.type.Array cfArray	=	creationUtil.createArray();

// create CF Struct
railo.runtime.type.Struct cfStruct	=	creationUtil.createStruct();	

// create CF Query named qNames with two columns (firstName and lastName) and 1 row
railo.runtime.type.Query cfQuery	=	creationUtil.createQuery( new String[]{ "firstName","lastName" }, 1, "qNames" );

Decision Util

Decision decisionUtil = engine.getDecisionUtil();

if ( decisionUtil.isDate( obj, false ) || decisionUtil.isStruct( obj ) );

Operations Util

Operation opUtil = engine.getOperatonUtil();
int c = opUtil.compare( left, right );	// cfml comparison rules
if ( c < 0 ) { 
	// negative value = "left" is Less Than "right"
} else if ( c > 0 ) {
	// positive value = "left" is Greater than "right"
} else {
	// zero = "left" Equals "right"
}

Casting

Cast castUtil	=	engine.getCastUtil();
castUtil.toArray( obj );
castUtil.toStruct( obj );

Exceptions Util

Excepton exp = engine.getExceptionUtil();

if ( doAbort ) 
	throw exp.createAbort();
else 
	throw exp.createApplicationException( "this is wrong", "you cannot ..." );

Evaluate

Object	obj =	pc.evaluate( "url.test=len( 'Railo is awesome!' )" );	// same as function evaluate(string)

Serialize

(new in Railo 4.0)

String	str =	pc.serialize( obj ); 					// same as function serialize(object)

see also the tutorial: Using Java in Railo: http://wiki.getrailo.org/wiki/Tutorial-using_Java_in_Railo

Category-Java

using_Railo_in_Java - getrailo/railo GitHub Wiki

Table of Contents