Support for external applications was removed from XperienCentral in version R29.3.

In This Topic

Using the application integration, any external web application can be integrated with XperienCentral. The design can be adapted to the design used in XperienCentral. Four application integration filters come standard with the product:

The WM Include filter retrieves the content of an external web application.
The WM ReplacementsFilter executes a series of replacements in the content that the WM Include filter has retrieved.
The XSLFilter converts XML into HTML.
Using the IncludeFileFilter, a file from disk can be used.

WM Include Filter

This application filter makes it possible to pull in content of an external web application in XperienCentral. Various parameters, such as the name of the external application server, the application’s URL, and a redirect page if something goes wrong can all be included.

IncludeFileFilter

XperienCentral comes standard with a filter (the WM Include filter) to embed external web applications. To test other filters with test input, it is useful to be able to include the content of a file. The IncludeFileFilter can be used for this.

The definition of the filter looks like this:

The code for defining this filter is as follows:

package nl.gx.webmanager.servlet.applications;

/**A smple filter that writes the content of a file to the response output stream. This filter may be used to
test the application integration module and is especially useful to test other filters.
*/

public class IncludeFileFilter implements Filter {

	private String filename;

	public void init(FilterConfig config) throws ServletException {
		// get the filename from the configuration
		filename = config.getInitParameter("filename");
	}

	public void doFilter(ServletRequest req, ServletResponse res, FilterChain chain) throws IOException, ServletException {

	// get a writer 
	PrintWriter writer = res.getWriter();

	// create a reader for the file
	FileReader fileReader = new FileReader(new File(filename));
	BufferedReader br = new BufferedReader(fileReader);

	// write the file content
	int charsRead;
	char[] buffer = new char[4096];

	try {
		while ((charsRead = br.read(buffer)) != -1) {
			writer.write(buffer, 0, charsRead);
		}
	} finally {
	// be sure to close the reader properly
		br.close();
	}
	// call the next filter
	chain.doFilter(req, res);
	}

	public void destroy() {
	}
}

Back to Top

WM ReplacementsFilter

This application filter uses a series of replacements to transform content. First, the content is retrieved. Then, one by one, the replacements take place. And finally, the content is returned. The definition of the filter is as follows:

Back to Top

XSLFilter

A relatively common scenario is that a web application delivers XML instead of HTML. This XML then needs to be transformed into HTML. The XLSFilter makes this possible. The definition of the filter is as follows:

The code for defining this filter is as follows:

package nl.gx.webmanager.handler.servlet.applications;

/**
This filter transforms the XML that is written to the response with XSL that is fetched from the
specified URL. It wraps the response so that the XML that is written to it is transformed on the fly.
The XSL can come from a URL, a file or a resource (obtained using the classloader).
*/

public class XSLFilter implements Filter {

	public void doFilter(ServletRequest req, ServletResponse res,FilterChain chain) throws IOException, ServletException {
		// wrap the response and let other filters/servlets write the XML that needs to be transformed
		CharResponseWrapper responseWrapper = new CharResponseWrapper((HttpServletResponse)res, servletContext);
		chain.doFilter(req,responseWrapper);

		// get input reader for the XSL 
		Reader r;
		if(xslUrl != null) {
		// download the XSL
			r = getXslFromUrl(xslUrl);
		} else if(xslResource != null){
			// get the XSL as a resource from the classpath
			r = new InputStreamReader(getClass().getClassLoader().getResourceAsStream(xslResource));
		} else if(xslFile != null) {
			// get the XSL from a file
			r = new FileReader(xslFile);
		}

		// read the stylesheet into a String
		try {
			String line;
			while((line = br.readLine()) != null) {
				pw.println(line);
			}
		} finally {
			// always clean up
			try { br.close(); }
			finally { pw.close(); }
		}
		String stylesheet = sw.getBuffer().toString();
		LOG.finest(stylesheet);

		// use the wrapped response as input
		StringReader xmlReader = new StringReader(responseWrapper.toString());

		// transform using the XSL transformer pool from XMLUtil.
		try {
			XMLUtil.transform(stylesheet, xmlReader, res.getWriter());
		}

	}
	Private Reader getXslFromUrl(String url) throws IOException, HttpException {
		// get the XSL from the URL
		HttpClient client = new HttpClient();
		GetMethod get = new GetMethod(url);
		client.executeMethod(get);
		int statusCode = get.getStatusCode();
		InputStream is = get.getResponseBodyAsStream();
		return new InputStreamReader(is, get.getResponseCharSet());
	}

	public void destroy() {
		LOG.info("XSLFilter destroyed");
	}
}

First, the response is wrapped. The wrapper catches all output to res.getWriter() and buffers it in a byte array that later can be read (ByteArrayInputStream). Next, the doFilter is activated in order to allow the filters that write XML (the IncludeFileFilter, for example), to do their job and write their output to the BufferingResponseWrapper. Then, an InputStream for the XSL is created and an XSL transformer is constructed. The final result of the transformation is written to the res.getWriter().

Back to Top

New Filters

The following steps have to be taken to integrate an application in XperienCentral and show it on a page:

Program additional filters if the standard filters do not suffice.
Include these filters in Tomcat.
Configure references to these filters in XperienCentral.
Define an application.
Indicate the application server hosting this application.
Indicate, if present, the proxy server hosting this application.
Assign filters to this application.
Show this application on a page.

If the standard filters are sufficient, Steps 1 through 3 can be skipped.

Step 1 – Programming a New Filter

The HelloWorldFilter is a simple example of a filter. This filter prints a message on a XperienCentral page if it is used with an application element. Filters are created as a Java classes:

package nl.yoursite.filters;

import java.io.IOException;

import javax.servlet.Filter;
import javax.servlet.FilterChain;
import javax.servlet.FilterConfig;
import javax.servlet.ServletException;
import javax.servlet.ServletRequest;
import javax.servlet.ServletResponse;

public class HelloWorldFilter implements Filter {
	private String message;
    public void init(FilterConfig config) throws ServletException {
		// Get the message from the configuration:
		message = config.getInitParameter("message");
	}

	public void doFilter(ServletRequest req, ServletResponse res, FilterChain chain) throws IOException, ServletException {
	// Write something to the output stream:
	res.getWriter().print(message);
	// Call the next filter:
	chain.doFilter(req,res);
	}
	public void destroy() {
	}
}

As shown in the code above, there are no nl.gx.* packages imported. The filter is completely independent of XperienCentral and works also in a normal servlet container. This is standard use for filters.

The javax.servlet.Filter API defines three methods implemented in this example:

The init method is used to retrieve parameters. In this case, one parameter (message) is retrieved.
In the doFilter method, the message is printed in a PrintStream from the response. The resulting string is shown on a page.

Do not use the getOutputStream method from the ServletResponse class. Using this method will result in a Java exception.

The last line in the doFilter method activates the next filter in the FilterChain. Functionality may remain after this call. It is also possible to wrap the response object in an HttpResponseWrapper implementation, so it can be used after the call.

The destroy method allows defining those actions that should be taken if the filter is ended.

Step 2 – Adding the New Filter to Tomcat

New filters should be created as Java files (in this case, HelloWorldFilter.java). The Java class should be included in a JAR file.

Create a folder structure on disk that is similar to:

\helloworldfilter\pom.xml
\helloworldfilter\src\main\java\nl\yoursite\filters\HelloWorldFilter.java

Maven requires this folder structure as well as a pom.xml file to be able to build your class.

A sample pom.xml:

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">
	<modelVersion>4.0.0</modelVersion>
	<parent>
		<artifactId>XperienCentral-libraries</artifactId>
		<groupId>nl.gx.webmanager.libraries</groupId>
		<version>10.11.0</version>
	</parent>
	<artifactId>project-applicationintegrationfilters</artifactId>
	<version>1.0.0</version>
	<name>project-applicationintegrationfilters</name>
	<description>
		Project-specific filters for application integration
	</description>
	<url>www.yoursite.com</url>
	<build>
		<defaultGoal>package</defaultGoal>
	</build>

	<dependencies>
		<dependency>
			<groupId>javax.servlet</groupId>
			<artifactId>servlet</artifactId>
			<scope>provided</scope>
		</dependency>
		<dependency>
			<groupId>javax.servlet</groupId>
			<artifactId>jsp-api</artifactId>
			<version>2.0</version>
			<scope>provided</scope>
		</dependency>
		<dependency>
			<groupId>nl.gx.webmanager.libraries</groupId>
			<artifactId>XperienCentral-api</artifactId>
			<version>${pom.parent.version}</version>
			<scope>provided</scope>
		</dependency>
		<dependency>
			<groupId>nl.gx.webmanager.libraries</groupId>
			<artifactId>XperienCentral-apiimpl</artifactId>
			<version>${pom.parent.version}</version>
			<scope>provided</scope>
		</dependency>
		<dependency>
			<groupId>nl.gx.webmanager.libraries</groupId>
			<artifactId>XperienCentral-handler</artifactId>
			<version>${pom.parent.version}</version>
			<scope>provided</scope>
		</dependency>
	</dependencies>
</project>

To build the class file, perform the following steps:

Open a Command prompt.
Navigate to the helloworldfilter folder.
Enter the command mvn -s <xperiencentral-root>/settings.xml clean package. The package is created:

If there are compilation errors, they will be shown in the window. If Maven’s build is successful, the class files are packed in a JAR file and placed in the folder \helloworldfilter\target\.
Copy the JAR to the WEB-INF/lib folder where all the other JARs are located (if you copied the Jar-file while Tomcat was running, you have to restart Tomcat before the Jar file will be picked up). As a result of that, XperienCentral knows that the filter exists. Now the filter can be used in the application integration module.

Step 3 – Adding the New Filter to XperienCentral

An application in the application integration module consists of a pipeline of filters that produces the desired output. To use the HelloWorldFilter, a (series of) filter(s) need to be defined in XperienCentral. Create a filter for the HelloWorldFilter and add the "message" parameter:

Field	Description
`Name`	Name of the filter as it appears in the selection lists.
`Description`	Description of the filter.
`Classname`	Name of the Java package and class that implement this filter.
`Parameter - Configuration name`	Internal name of the parameter.
`Parameter - Type`	For self-defined filters, the type is always "String". For predefined filters, the type can be something else, such as "Page", "Boolean", or "Replacements".
`Parameter - Name`	External name of the parameter.

The predefined filters cannot be edited on this tab.
If there is an application on a page, /application is added to the URL. This activates the filters. There is only one exception: /application is never added to the URL of the home page. It is common behavior not to put an external application on the home page.

To test if this filter works, add it to a new application and set the parameter:

Add the application to a page (through the Insert > Application menu) and select the previously created application:

Once the filter has been tested, it can be used in an application.