This topic is for developers who want to build applications using FME Server REST API in Java. This topic contains code for common requests with FME Server REST API.
The JavaScript version handles json replies, whereas the Java version uses the xml version. To see the html version, go to http://<host>:<port>/fmerest.
Many common operations such as obtaining a server session, managing repository items and resources, and running workspaces are outlined. Please note that the sample code provided is intended for demonstration purposes only:
For the purpose of this tutorial, we will be using a built in XML parser in Java. First, we must import the required packages:
import javax.xml.parsers.DocumentBuilder;
import javax.xml.parsers.DocumentBuilderFactory;
Let us also create a function that can take a string and transform it to an XML document.
private Document parseXML(String contents) throws Exception
{
DocumentBuilderFactory dbf = DocumentBuilderFactory.newInstance();
DocumentBuilder db = dbf.newDocumentBuilder();
InputSource is = new InputSource();
is.setCharacterStream(new StringReader(contents));
Document doc = db.parse(is);
return doc;
}
The simplest method to authenticate a user using the REST API is through the fmetoken security.
First, generate a token for a set period of time using the user's credentials.
For the duration specified, the token will be valid, and should be used whenever accessing the REST API.
String fmeUrl = "http://"+host_+":"+port_+"/fmetoken/service/generate";
PostMethod method = new PostMethod(fmeUrl);
method.addParameter("user", userid_);
method.addParameter("password", password_);
method.addParameter("expiration", "1");
method.addParameter("timeunit", "hour");
if (client_.executeMethod(method) == 200)
{
token_ = method.getResponseBodyAsString();
}
else
{
throw new Exception("Authentication failed");
}
A repository is a central place to store items, resources and other things that enable the FME Server to perform its functions. A typical item is a workspace, a custom format or a custom transformer. Associated with items are resources.
How to list available repositories
Listing repositories requires a GET request, with no parameters.
String fmeUrl = "http://"+host_+":"+port_+"/fmerest/repositories.xml?token="+token_;
GetMethod method = new GetMethod(fmeUrl);
client_.executeMethod(method);
String contents = method.getResponseBodyAsString();
Document doc = parseXML(contents);
NodeList nl = doc.getElementsByTagName("repository");
for (int s = 0; s < nl.getLength(); s++) {
System.out.println(((Element)nl.item(s)).getElementsByTagName("name").item(0).getTextContent());
}
How to add repositories
Repositories are uniquely identified by their name. A new repository can be created by specifying a new repository name and a repository description. Adding a repository requires a POST method, with the parameters sent.
Note: If you don’t check if a repository with the same name already exists and then add a repository with the same name, the existing repository will be overwritten.
String fmeUrl = "http://"+host_+":"+port_+"/fmerest/repositories.xml?token="+token_;
PostMethod method = new PostMethod(fmeUrl);
method.addParameter("repository", name);
method.addParameter("description", description);
if (client_.executeMethod(method) != 200)
{
throw new Exception("Repository creation failed: " + method.getResponseBodyAsString());
}
How to remove repositories
Removing a repository requires the name of the repository. It’s important to know that removing a repository will also remove any items and resources in it.
String fmeUrl = "http://"+host_+":"+port_+"/fmerest/repositories/"+name+".xml?token="+token_;
DeleteMethod method = new DeleteMethod(fmeUrl);
if (client_.executeMethod(method) != 200)
{
throw new Exception("Repository deletion failed");
}
A workspace is a type of repository item so the concepts in this section will also apply to other repository items such as custom formats and custom transformers. A workspace normally has an FMW file extension, whereas custom formats have a FDS file extension and custom transformers have a FMX file extension.
FME workspaces are created through FME Workbench and can be published to an FME Server repository so that multiple users can access them. Workspaces in the FME Server repository can also be downloaded, modified, and then published again.
A default installation of FME Server comes with a number of demo workspaces but most users will create their own workspaces. In this section, it’s assumed you will either use one of the demo workspaces or create a workspace of your own using FME Workbench.
How to list workspaces in a repository
Workspace names can be quickly listed using repository methods that get the workspace summaries of a workspace. More detailed information about workspaces can be fetched with the uri's provided.
String fmeUrl = "http://"+host_+":"+port_+"/fmerest/repositories/"+name+".xml?token="+token_;
GetMethod method = new GetMethod(fmeUrl);
client_.executeMethod(method);
String contents = method.getResponseBodyAsString();
Document doc = parseXML(contents);
NodeList nl = doc.getElementsByTagName("workspace");
for (int s = 0; s < nl.getLength(); s++) {
System.out.println(((Element)nl.item(s)).getElementsByTagName("name").item(0).getTextContent());
}
How to add workspaces to a repository
To add a new workspace to a repository, the repository name, the workspace file path (ie. "C:\myworkspaces\foo.fmw") and the workspace name (ie. foo.fmw) are required. When adding a workspace, the actual workspace file is uploaded to the FME Server repository.
String fmeUrl = "http://"+host_+":"+port_+"/fmerest/repositories/"+repositoryName+"/"+workspaceName+".xml?token="+token_;
PutMethod method = new PutMethod(fmeUrl);
method.setRequestEntity(
new FileRequestEntity(
new File(workspaceFilePath), "doesn't matter")
);
if (client_.executeMethod(method) != 200)
{
throw new Exception("Adding workspace failed");
}
How to get workspaces from a repository
To get a workspace from a repository, the repository name, the local workspace file path (ie. C:\myworkspaces\foo.fmw) and the workspace name (ie. foo.fmw) are required. The workspace name uniquely identifies a workspace in a repository and should match the workspace you wish to get. When getting a workspace, the actual workspace file is downloaded from the FME Server repository to the specified local workspace file path.
String fmeUrl = "http://"+host_+":"+port_+"/fmerest/repositories/"+repositoryName+"/"+workspaceName+".xml?token="+token_;
GetMethod method = new GetMethod(fmeUrl);
FileOutputStream file = new FileOutputStream(workspaceFilePath);
PrintStream fileStream = new PrintStream(file);
if (client_.executeMethod(method) != 200)
{
throw new Exception("Getting workspace failed");
}
byte[] responseBody = method.getResponseBody();
// Deal with the response.
// Use caution: ensure correct character encoding and is not binary data
fileStream.println(new String(responseBody));
fileStream.close();
file.close();
How to remove workspaces in a repository
To remove a worksapce in a repository, the repository name and the workspace name are required.
String fmeUrl = "http://"+host_+":"+port_+"/fmerest/repositories/"+repositoryName+"/"+workspaceName+".xml?token="+token_;
DeleteMethod method = new DeleteMethod(fmeUrl);
if (client_.executeMethod(method) != 200)
{
throw new Exception("Workspace deletion failed");
}
Some workspaces may require resources to successfully run. Any resources associated with a workspace are placed with the workspace and are accessed through the repository object.
How to list resources for a workspace
To view the resources that already exist for a workspace, the repository name and the workspace name are required.
String fmeUrl = "http://"+host_+":"+port_+"/fmerest/repositories/"+repositoryName+"/"+workspaceName+"/resources.xml?token="+token_;
GetMethod method = new GetMethod(fmeUrl);
client_.executeMethod(method);
String contents = method.getResponseBodyAsString();
Document doc = parseXML(contents);
NodeList nl = doc.getElementsByTagName("resource");
for (int s = 0; s < nl.getLength(); s++) {
System.out.println(((Element)nl.item(s)).getElementsByTagName("name").item(0).getTextContent());
}
How to add resources for a workspace
To add a new resource for a workspace, the repository name, the workspace name, the resource file path (ie. C:\myresources\resource.csv) and the resource name (ie. resource.csv) are required. When adding a resource, the actual resource file is uploaded to the FME Server repository.
String fmeUrl = "http://"+host_+":"+port_+"/fmerest/repositories/"+repositoryName+"/"+workspaceName+"/resources/"+resourceName+".xml?token="+token_;
PutMethod method = new PutMethod(fmeUrl);
method.setRequestEntity(
new FileRequestEntity(
new File(resourceFilePath), "")
);
if (client_.executeMethod(method) != 200)
{
throw new Exception("Resource addition failed");
}
How to get resources for a workspace
To get a resource for a workspace, the repository name, the workspace name, the local resource file path (ie. C:\myresources\resource.csv) and the resource name (ie. resource.csv) are required. The resource name uniquely identifies a resource for a workspace and should match the resource you wish to get. When getting a resource, the actual resource file is downloaded from the FME Server repository to the local resource file path.
String fmeUrl = "http://"+host_+":"+port_+"/fmerest/repositories/"+repositoryName+"/"+workspaceName+"/resources/"+resourceName+".xml?token="+token_;
GetMethod method = new GetMethod(fmeUrl);
if (client_.executeMethod(method) != 200)
{
throw new Exception("Resource download failed");
}
FileOutputStream file = new FileOutputStream(resourceFilePath);
PrintStream fileStream = new PrintStream(file);
byte[] responseBody = method.getResponseBody();
// Deal with the response.
// Use caution: ensure correct character encoding and is not binary data
fileStream.println(new String(responseBody));
fileStream.close();
file.close();
How to remove resources for a workspace
To remove a specific resource from a workspace, the repository name, workspace name, and resource name are required. Removing a specific workspace will also remove all associated resources for the workspace.
String fmeUrl = "http://"+host_+":"+port_+"/fmerest/repositories/"+repositoryName+"/"+workspaceName+"/resources/"+resourceName+".xml?token="+token_;
DeleteMethod method = new DeleteMethod(fmeUrl);
if (client_.executeMethod(method) != 200)
{
throw new Exception("Resource deletion failed");
}
Services require administrative privileges to access. The token service should be enabled (default installation).
How to list available services
Listing services requires the GET method and the url.
String fmeUrl = "http://"+host_+":"+port_+"/fmerest/services.xml?token="+token_;
GetMethod method = new GetMethod(fmeUrl);
client_.executeMethod(method);
String contents = method.getResponseBodyAsString();
Document doc = parseXML(contents);
NodeList nl = doc.getElementsByTagName("service");
for (int s = 0; s < nl.getLength(); s++) {
System.out.println(((Element)nl.item(s)).getElementsByTagName("name").item(0).getTextContent());
}
How to add services
To add a new service, the service name, service display name, description and URL pattern are required. If there is an existing service with the same name, it will be replaced.
String fmeUrl = "http://"+host_+":"+port_+"/fmerest/services.xml";
PostMethod method = new PostMethod(fmeUrl);
method.addParameter("token", token_);
method.addParameter("service", name);
method.addParameter("description", description);
method.addParameter("displayname", displayName);
method.addParameter("urlpattern", urlPattern);
method.addParameter("isenabled", "true");
method.addParameter("isregallowed", "true");
if (client_.executeMethod(method) != 200)
{
throw new Exception("Service creation failed");
}
How to remove services
To remove a service, only the service name which uniquely identifies the service is required.
String fmeUrl = "http://"+host_+":"+port_+"/fmerest/services/"+name+".xml?token="+token_;
DeleteMethod method = new DeleteMethod(fmeUrl);
if (client_.executeMethod(method) != 200)
{
throw new Exception("Service deletion failed");
}
Once a workspace is published to an FME Server repository, the workspace can be run. This can be done by constructing and then sending a GET request to the URL as defined by the REST API documentation. Normally users would create their own workspaces, but for this example we will be using a demo workspace that is included with the default installation of the FME Server.
Some workspaces have published parameters that can be set. Some have default values but others need to be explicitly set before we are able to run the workspace. These depend on the workspace itself.
To get a list of the published parameters available for the workspace:
String fmeUrl = "http://"+host_+":"+port_+"/fmerest/repositories/"+repositoryName+"/"+workspaceName+"/parameters.xml?token="+token_;
GetMethod method = new GetMethod(fmeUrl);
client_.executeMethod(method);
String contents = method.getResponseBodyAsString();
Document doc = parseXML(contents);
NodeList nl = doc.getElementsByTagName("parameter");
for (int s = 0; s < nl.getLength(); s++)
{
System.out.println(((Element)nl.item(s)).getElementsByTagName("name").item(0).getTextContent());
}
To set such a published parameter - in this case MAXY - add it to the parameter to be sent:
method.addParameter("MAXY", "50");
Note: Values for published parameters must always be passed as a string, regardless of what they actually represent.
There also exist directives that are always available from the FME Server. A list of TM directives can be found in Transformation Manager Directives. For our example, we set a high value for the priority of this job, in order to tell the FME Server to execute it before other tasks. This is not necessary but just done to illustrate how to set directives.
method.addParameter("tm_priority", "50");
The transformation result has a number of methods for obtaining different parts of information from the FME Server response. In our example we parse and display a few important points from the string that was received from the server. In certain scenarios, the clients may want to do their own parsing on this string instead of relying on the provided methods.
String fmeUrl = "http://"+host_+":"+port_+"/fmerest/repositories/"+repositoryName+"/"+workspaceName+"/run.xml";
PostMethod method = new PostMethod(fmeUrl);
method.addParameter("token", token_);
// add published parameters
System.out.println("Sending a transformation request to the FME Server...\n");
// Submit the transformation request. This method will block until
// transformation results are available. (Users who wish to submit jobs
// asynchronously should instead use set the parameter to asynchronous method.)
client_.executeMethod(method);
String contents = method.getResponseBodyAsString();
Document doc = parseXML(contents);
NodeList nl = doc.getElementsByTagName("fmeServerResponse");
System.out.println("The following information was parsed from the response:\n");
System.out.println("============");
for (int s = 0; s < nl.getLength(); s++)
{
System.out.println("Job Status: "+((Element)nl.item(s)).getElementsByTagName("jobStatus").item(0).getTextContent());
System.out.println("Job Id: "+((Element)nl.item(s)).getElementsByTagName("id").item(0).getTextContent());
}
System.out.println("============");
How to list all jobs
Jobs fall into one of four categories: completed, queued, scheduled, and running. In order to list each job, we must iterate through all the categories.
String[] categories = {
"running",
"completed",
"scheduled",
"queued"
};
for (String category : categories)
{
String fmeUrl = "http://"+host_+":"+port_+"/fmerest/jobs/"+category+".xml?token="+token_;
GetMethod method = new GetMethod(fmeUrl);
client_.executeMethod(method);
String contents = method.getResponseBodyAsString();
Document doc = parseXML(contents);
NodeList nl = doc.getElementsByTagName("job");
System.out.println(category + ":");
for (int s = 0; s < nl.getLength(); s++)
{
System.out.println(((Element)nl.item(s)).getElementsByTagName("ID").item(0).getTextContent());
}
}
How to view the details of a job
To view the details of a specific job, the job ID is required.
String fmeUrl = "http://"+host_+":"+port_+"/fmerest/jobs/"+id+".xml?token="+token_;
GetMethod method = new GetMethod(fmeUrl);
client_.executeMethod(method);
String contents = method.getResponseBodyAsString();
Document doc = parseXML(contents);
NodeList nl = doc.getElementsByTagName("job");
for (int s = 0; s < nl.getLength(); s++)
{
System.out.println(((Element)nl.item(s)).getElementsByTagName("ID").item(0).getTextContent());
// add any extra things to view here;
}
How to delete finished jobs
As jobs are completed, the list piles up. To clear the list of finished jobs, simply send a DELETE request.
String fmeUrl = "http://"+host_+":"+port_+"/fmerest/jobs/completed.xml?token="+token_;
DeleteMethod method = new DeleteMethod(fmeUrl);
if (client_.executeMethod(method) != 200)
{
throw new Exception("Job deletion failed");
}
How to cancel a queued job
To cancel a queued job, the job ID is required.
String fmeUrl = "http://"+host_+":"+port_+"/fmerest/jobs/"+id+"/cancel.xml?token="+token_;
PostMethod method = new PostMethod(fmeUrl);
if (client_.executeMethod(method) != 200)
{
throw new Exception("Job cancellation failed");
}