 |
|
 |
|
|
|
The Galaxy Plugin for Eclipse provides an easy way to access a M31.Galaxy server. This document shows the usage of the Plugin based on a step by step tutorial.
Lets assume, there is a little company called TSC Inc. which needs a simple Address book. They have only five employees, but since they all have a lot of things in their mind, they keep forgetting their own numbers and email addresses. So they got you to write a little Application for them...
Requirements
To follow this tutorial, you need to...
... download and install the SAGA M31.Galaxy Eclipse Plugin from http://galaxy.sagadc.com/. The installation package contains the instruction for the installation
... decide wether you want to setup a SAGA M31.Galaxy Server yourself or to use our M31.Galaxy sample server at http://galaxy.sagadc.com/Galaxy/wui
In the first case, you will need to:
Create the SampleApplication with Eclipse
This section describes how to build the actual Java application with the help of the M31.Galaxy Eclipse Plugin.
First you need to create a new Java-Project in your Workspace. In our example we called it GalaxySampleApp, but feel free to choose another name if you like to do so.
Next thing you need to do is add the Galaxy Runtime libraries to the classpath of your project. The runtime libraries are bundled in the GalaxyRuntime.zip file you received with the download of the M31.Galaxy Eclipse Plugin. Unzip the three jars to a directory of your choice and add all of them to the project. Finally your project should look similar to this screen shot:
To enable your Project to use Galaxy requests, open it's context menu and choose the entry "Add Galaxy support".
This will create a Galaxy configuration file called "galaxy.cfg.xml" inside of the project:
Additionally the Editor provided with the plugin will be started:
To understand the way, the editor is working, we will first go into some details of the GalaxyAPI and the configuration of it.
The GalaxyAPI and its configuration file
M31.Galaxy comes with a simple JavaAPI to access the containers on a M31.Galaxy server.
It supports you to run containers by executing the following tasks:
In this way it hides the handling of with XML and communicating with the galaxy server from your code so you can focus on the requirements of your program.
How it works
The API consists of two important types:
GalaxyRequest
The first is the com.sagadc.galaxy.api.GalaxyRequest-Interface, which defines Methods to run a Container at a particular M31.Galaxy-Server.
The important methods are:
addInputItem(String itemName, Object itemValue)
When doing a request that needs input data, this method can be used to set the input items. You specify the name of the input item with itemName, and the value of it with itemValue.
doRequest()
Triggers the request by translating the prior set input items into a XML structure and posting it against the M31.Galaxy server. The received XML structure is translated back into a java structure of Maps and Lists.
getReturnCode() and getMessage()
After calling the doRequest() method on a GalaxyRequest, you can check the status of a container run with the help of these two methods.
If getReturnCode() returns a value of zero, the request was handled properly and you can access the output items that where returned by the request. Otherwise, an error has occurred during the container run. In this case, the getMessage() method will give you a more detailed information about what went wrong.
Note that you should always check for an return code of zero before accessing one of the output items.
getOutputItem(String itemName)
After doRequest() returned, you can access a particular output item that was returned by the container run by using this method. You specify the name of the desired item with itemName and will get an Object that represents the output item. The returned value can be of two different java types in this version, depending on the data type that is defined in the container:
The returned value will be an instance of the java.lang.String class and can be used as such.
The returned value will be an instance of the type java.util.List whereby each item of the list represents one row inside of the provided table. Each row itself will be an instance of the type java.util.Map, where the key is the name of the column and the value is the actual value of the table cell.
getOutputItems()
Returns a instance of the type java.util.Map which represents all fields that where returned by the container run. The keys of this map represents the names of the fields, the values their value. This is just another way to access the result of the container run, so a call to getOutputItem("aItem") would be similar to a call to getOutputItems().get("aItem").
The other methods defined in this interface are used by the factory to initialize the GalaxyRequst instance and are not required to be called by code using the API.
GalaxyFactory
The second type of the API is the com.sagadc.galaxy.api.GalaxyFactory which is used to create instances of the GalaxyRequest interface.
The class provides a static method, getFactoryInstance() to access the default instance of the factory. In this way you don't need to keep a reference to the factory inside of your code. The implementation of the method is done with lazy instantiation, which means, that only the first call to it will really create a factory and parse the configuration file. All following callers will get satisfied by returning the prior created instance of the class.
The way that the GalaxyFactory works is that it reads its configuration from a xml file. In the default case, this is called "galaxy.cfg.xml", and searched at the root of your classpath. The file is the one that you have created when choosing the "Add Galaxy Support" action on the newly defined project.
The factory configuration file (galaxy.cfg.xml)
Before going into the functionality of the GalaxyFactory more deeply, lets first have a quick look on the content of a galaxy configuration file:
[1] <galaxy-factory>
[2] <servers>
<server id="SampleServer">
<url>http://an.m31.server.de/Galaxy</url>
<username>admin</username>
<password>e03239b27e34a5f7f3bde739459dd537</password>
</server>
[... more servers here ...]
</servers>
[3] <requests>
<request id="TestRequest" target="SampleServer">
<containername>ContainerLDAP</containername>
</request>
[... more requests here ...]
</requests>
</galaxy-factory>
A sample galaxy.cfg.xml
The file is structured into two sections, which are nested in the galaxy-factory root node.
The first section [2] defines all the servers used inside of this configuration. Each server has the following properties:
| id | an internally used name to reference the servers from the request section [3] |
| url | the base URL of the M31.Galaxy Server, used to construct the URL for the Request |
| username | the name that is used to authenticate against the server |
| password | an MD5 hash of the password that belongs to the defined username |
The second section [3] defines the requests that you can use inside of your code. Each request is defined by the following properties:
| id | A name for the request. In your java code you will use that name to obtain an GalaxyRequest instance for this request. |
| target | The id of the server, this request should run again. |
| containername | The handle of the container which this request should run. |
Using the factory to obtain a GalaxyRequest instance
After looking into the file structure it should be easy to understand the approach of the GalaxyFactory:
You can ask the factory to create instances of the GalaxyRequest for you. This is done by calling the getRequest(String requestName) on the factory which will create the request specified by requestName.
What the factory is doing when this method is called is to look up weather a request with this id is defined in the loaded configuration. If so, a new GalaxyRequest is created and initialized with its container name. Then it searches for a server with the id of the requests target attribute of. The properties url, username and password from the server are placed in the newly created instance of GalaxyRequest.
Now, that the request knows where to go (url), how to authenticate (username and password) and what to do (containername) it is ready to be returned to your code and do its work.
Enough of the theory, lets do some coding
Be patience, we will get there in a second, but first you need to setup the two requests that will be used...
You can easily do this with the editor provided with the M31.Galaxy Eclipse Plugin. This editor contains a front end to define the requests via a user interface as well as an source editor for the galaxy configuration file. You can switch between the two views at the bottom of the editor view.
First action is to create a Server. Open the context menu on the "Explore Servers" area:
Choose the "Add Server" Action, the following dialog will appear:
Insert a Name, the base URL of your M31.Galaxy installation, username and password and press OK.
If you have decided not to install M31.Galaxy yourself, you will need to provide the following values to connect to our M31.Galaxy server:
Base URL:http://galaxy.sagadc.com/Galaxy
Username:sample
Password:sample
The server configured behind this URL contains all the required containers to run the sample application
You will now see the name of the server that was entered in the dialog as a expandable item in the "Explore Server" area. If you extend it, you should see a list of all the containers that are defined on your Galaxy server. The containers themselves are expandable to show the input/output fields that this container needs or provides.
To finally define a request, open the context menu of the Container "All Users TSC Inc." and Choose the "Create Request" item:
A dialog will come up and ask you for the Name of the new Request. Enter "TSOUserList" and press the OK button
In the "Configured Requests" list you should see an entry for the created request which is titled "TSOUserList"
Repeat the same steps for the container called "User Contact Details TSC Inc." and give it the name "TSOUserDetails".
Your "Configured Requests" list should now contain two entries:
Save the configuration file by pressing Ctrl-S, you have completed the task to configure the GalaxyFactory.
The Sample Application
Now, that the configuration is done, you can start implementing the application itself.
The source shown on this page has been cut down to the parts which demonstrate the usage of the GalaxyAPI. The two functions getUserSelection() and checkReturncode() are not shown in the listing. The full source of the application is available here
Lets have a look at the implementation of the sample application:
public class GalaxySample
{
//Input/Output fields, defined by Galaxy
private static final String OUT_LASTNAME = "LastName";
private static final String OUT_FIRSTNAME = "FirstName";
private static final String OUT_CONTACTID = "ContactId";
private static final String IN_USERID = "userID";
//Request names, defined by galaxy.cfg.xml
private static final String REQUEST_TSC_USERLIST = "TSCUserList";
private static final String REQUEST_TSC_DETAILS = "TSCUserDetails";
public static void main(String[] args) {
/*
* [1] Get the request called REQUEST_TSC_USERLIST from the factory
*/
GalaxyRequest listRequest = GalaxyFactory
.getFactoryInstance()
.getRequest(REQUEST_TSC_USERLIST);
/*
* [2] Run the request (No input fields are required)
*/
listRequest.doRequest();
checkReturncode(listRequest);
/*
* [3] Get the item, which represents the user table
*/
List userTable = (List) listRequest.getOutputItem("AllUsersTSC");
/*
* Print the list of user
*/
System.out.println("List of all users:");
System.out.println("------------------");
for(int i = 0; i < userTable.size(); i++)
{
Map currentRow = (Map) userTable.get(i);
System.out.println(i + ": "
+ currentRow.get(OUT_FIRSTNAME)
+ " "
+ currentRow.get(OUT_LASTNAME));
}
System.out.println("------------------");
/*
* [4] Get the users selection
*/
int selection = getUserSelection(userTable.size());
/*
* [5] Fetch the ID and shoot another request to get the details of the selected user
*/
Map selectedUser = (Map) userTable.get(selection);
Object selectedUsersId = selectedUser.get(OUT_CONTACTID);
/*
* [6] Get the Request called REQUEST_TSC_DETAILS
*/
GalaxyRequest detailRequest = GalaxyFactory
.getFactoryInstance()
.getRequest(REQUEST_TSC_DETAILS);
/*
* [7] Add the selected users id as inputItem
*/
detailRequest.addInputItem(IN_USERID, selectedUsersId);
/*
* Trigger the request (see [2])
*/
detailRequest.doRequest();
checkReturncode(detailRequest);
/*
* [8] Print out all outcomming items for the selected user
*/
Map userDetails = detailRequest.getOutputItems();
Iterator keys = userDetails.keySet().iterator();
System.out.println();
System.out.println("Details for selected User:");
System.out.println("--------------------------");
while(keys.hasNext())
{
String currentKey = keys.next().toString();
System.out.println(currentKey + ": " + userDetails.get(currentKey));
}
System.out.println("--------------------------");
}
[...]
}
Comments
[1] Get the request called "TSCUserList" from the factory
By calling the static method getFactoryInstance() on the GalaxyFactory class you can obtain a reference to the default instance of the factory which is configured via the configuration file "galaxy.cfg.xml" that the plugin has created for us. On this instance we call the getRequest() method to let the factory create a preconfigured instance of the GalaxyRequest interface
[2] Run the request (No input fields are required)
The doRequest() method triggers the request against the galaxy server. Since this container (TSCUserList) does not need any input data, you can call this method without a call to addInputItem() before (see comment 7 for details on this method)
[3] Get the item, which represents the user table
Since you know from defining the container that the result in item "AllUsersTSC" will be a table you can safely cast it into java.util.List (which is the GalaxyAPI representation of a Galaxy table)
Each item of this List will be of the type java.util.Map (which is the GalaxyAPI representation of a table row). Now, that you want to print out all the rows of the response you can simply iterate over the List fetch the items with the keys "LastName" and "LastName" and print them to the console
[4] Get the users selection
This logic was moved to another method because it has nothing to do with the handling of GalaxyAPI which should be demonstrated here. It asks the User to enter the number of the record, he want's to see details for.
[5] Fetch the ID and shoot another request to get the details of the selected user
At this point the selection of the user comes into play. The selected element is fetched from the userTable as a java.util.Map (remember, the representation of a row...). Since the element of the row contains the id of the record this is read in the next line by fetching the value of the key "ContactId" from the Map. The value is stored as Object, because its only sense is to get passed to the addInputItem() method in the next step (which also takes an Object as input)
[6] Get the Request called "TSCDetails"
Again, the factory creates another GalaxyRequest instance for us, which is used to fetch the details for the record selected by the user
[7] Add the selected users id as inputItem
This time, the container needs an input field, which is the id of the user the user has selected. Input fields are inserted into a request by calling the addInputData() method, which takes a String and an Object as parameter
The first argument represents the name of the input field ("userID"), the second one the value for it (the id of selected user)
[8] Print out all returned items for the selected user
The response is fetched via the method getOutputItems() this time, which returns a Map. Since the fields are provided directly with this container the Map contains the actual values instead of a List with nested Maps. This is the difference of tabular/non tabular responses with Galaxy.
The structure now only represents one row of the table, that's why you can simply iterate over the Maps keys to print out the key/value pairs.
Run the Sample Application
After writing the application, you can lunch it via eclipse, simply choose "Run"->"Run as"->"Java application". When the application asks you to select a User for details, enter one of the numbers from the list and the program will give you the details for the selected user:
Congratulations, you have completed your first application using SAGA M31.Galaxy.
If you have any problems working with this tutorial, questions or feedback you would like to report to us, please contact us via galaxy@sagadc.com or our website http://www.sagadc.de/de/aboutus/contact.php
Thank you for your interest on SAGA M31.Galaxy.
| » Imprint » Disclaimer » Terms » Contact » Privacy | © 2006, SAGA D.C. GmbH - All rights reserved  |
|