SAGA D.C. GmbH SAGA.M31 - Galaxy - Create Web Services in 15 minutes   SAGA D.C. GmbH
Introduction

Data access for a develop always entails the pain of learning a new system, a new way to access data, and dealing with data in new format. Be it Databases, ERM systems, LDAP Servers or any other data source, each has its own data access mechanism.

SAGA.M31 Galaxy is a server that creates a standard interface to data and providing data access via Open Standards like HTTP and Web Services. With Galaxy, as an example, you can give someone access to data that is sitting in an internal database over HTTP, so your network's security is never compromised. Previously to do something like this meant weeks of coding to create an application, plus time taken learning new technologies and standards.

With a standard interface that Galaxy provides to your data, you can switch the actual source of the data without affecting the interface. Data and Application Migration, which used to be a pain and cost thousands in development, is now a breeze.

In this tutorial, we will go through creating an LDAP Connector, from which we will get data via an LDAP Request and finally create a container that will access this data.

Requirements

SAGA.M31 - Galaxy is an J2EE (Java 2 Enterprise Edition) Web Application that needs a J2EE Application Server (that must have a Servlet Container) to run in. Galaxy has been tested on the following Application Servers:

J2EE Application Servers need a version of the Java Runtime Environment (JRE). We recommend Version 1.4.x of the JRE for Galaxy. The newer Java 5 and versions older than 1.4.x are not supported.

Apart from this, Galaxy needs a MySQL Database that it can access. MySQL can be freely downloaded from: MySQL. We recommend Version 4.0.x Series of MySQL.

Download and Installation

The Galaxy package can be downloaded at Galaxy Website. The installation instructions are included within the package in a file called install.txt. Before installaing Galaxy ensure that you have:

Create an LDAP Connector

From the Menu, select "Create Connector".

From the Create/Edit Connector page, select LDAP in the drop and click "GO!".

On this page, you must specify:

For connection to an LDAP Server, the server address and port are necessary. With out the Bind DN and Password, this connector will try to connect to the LDAP server anonymously.

With the "Add Configuration" button, you can define a backup LDAP Server. The Connector will then try to connect to the first server and if that fails, it will try the backup server(s). This fallback mechanism only makes sense when the backup servers have the same data as the main servers.

When all the necessary fields have been filled, press the "Save" button to save you settings.

Initial Login

Once installed, Galaxy Web User Interface (WUI) is accessable via the following URL:

http://[Host]:[Port]/Galaxy/wui
The Host and Port are specific to your Application Server.

A freshly installed Galaxy instancs has, by default, the login of:

Username: admin
Passwort: galaxy

Creating an LDAP Connector Request

To create a new LDAP Request, under the "Connector Requests" title choose, "LDAP Connector". This will take you to the LDAP Connector page that shows all LDAP Requests that have been previously been created. This page will show an empty list if no previous requests have been configured.

Click on the "Create New Request" to proceed to a wizard that will guide you through this process. This wizard allows you to make only 1 request at a time.

Step 1

In Step 1, the parameters for an LDAP Request are specified.

The following Parameters should be specified:

ParameterDescription
NameA name for this request
Target connectorThe LDAP Connector against which this request should run
Base DN A Base DN for this request
FilterThe Filter for this Request
Search ScopeThe Search Scope to use: Object, One Level or Sub-Tree Scope
Provide as TableWhen checked, will always return the results in a table
Error on empty resultWhen checked, will throw an error if the results of running this request are empty

In the Filter field you can create a variable. A variable can be thought of as input to an Request (and hence will eventually map to an input field of a Container). To create a variable, declare it with the following syntax: #variableName#.

Example: A LDAP Server for a company holds the information about all its customers. Every customer has its own Customer-Number that identifies it. Suppose our aim is to eventually create a Container that gives all the customer information given the Customer-Number. We would then configure an LDAP request that has a variable like #customerNumber# and would give out all the customer information.

Step 2

In Step 2, all the Variables created in Step 1 are listed along with fields to allow you to input a value so that the actual LDAP request can be done and you will see the results.

The results you will see in Step 3.

Step 3

In Step 3 the output fields that this LDAP request are defined. An output field can be created by selecting an attribute whose value we want. You can do this by pressing the "Add" link against the attribute (and its sample value). These defined fields can then be given (meaningful) names.

With the "Add Mapping" button, you can add an output field and specify the Mapped Attribute yourself. This is to cover the cases where the list of attributes returned (from the input in Step 2) does not contain an attribute that would otherwise be there.

Because in Step 1, we asked for Result to be provides as a table, we have to give the name of the table that will be provided. When the results of the LDAP request give more than one set of values, each row will then be filled with the set of the Defined Fields.

Click on "Save" and this request will be saved. We will now create a Container that will use this request.

Container Creation

A Containers, once created, can be used as a source of data via an XML Request/Response structure. The XML Request/Response structure for a container is independent from the Connectors from which a Container gets data. This separation means the connectors can be changed/exchanged without affecting the data.

A Container defines Container Field and these map to Connector Fields. The Container's Output Fields map to Connector Output Fields and similarly for Input Fields.

To create a Container, Click on "Create Container" from the Menu.

Step 1

In the first step, the connecter's names and description is filled in.

In the Summary field, you should put in a short description of this container.

In the Handle field, you should put in a 1-word name for this container that will be used in creating the WSDL link for this container. A Handle is necessary for the generation of the WSDL and the access of the container via the V2 XML Request-Reponse Structure.

In the Description fields, you should describe your container in detail.

The WSDL public available checkbox decides if the WSDL for this container if available publicly via the following URL:

http://[Host]:[Port]/Galaxy/wsdl/[ContainerHandle].wsdl

The Host, Port and ContainerHandle must be filled in according to your server and Containers.

If a Container's WSDL is not public, then you can still view it via the Container List Page, provides you have administrative access.

Step 2

Click "Next step" and all the information you entered will be checked, and if all is ok, you will be directed to Step 2.

In the drop down list "Fields in Connector" select the connector that we just created. The Fields shown will then only be the ones that this connector provides. You can create a new Container field, by clicking add against a connector field. This will create a Container field that maps the connector against which you just clicked "Add".

Each Container Fields can be given a name under the "Field Name" field. Even when a Connector Fields that a Container Fields maps to changes, the Container Field stays the same. This allows data migration with surprising ease.

Tip: You can put fields from multiple Connectors in one Container. Galaxy will then:

Step 3

Click on "Next Step" to proceed to Step 3. Here all the input fields for the Connector Fields that were chosen in Step 2 will be resolved. All you need to do is map them to Container Input Fields.

To cerate a new Container Input Field that maps to a Connector Input Field, simply click on the "Add as new" against the Connector Field.

As in Step 2, you can assign your own name to a Container's Input field.

Step 4

Clicking on "Next Step" will take you to Step 4: the overview.

Here you can review all you changes and once satisfied, click on "Save Container" to save the changes and create this Container.

Testing the Container

To test the container via the WUI, you will need to do a "Sample Run." Click on the "Manage Containers" from the Menu and you will be taken to the Container List Page.

Click on the "Sample Run" link against the container you just created.

On this page, you will any Container Input Fields as input fields in which you can put in some sample data, press "Fire!" and see the output of running this Container.

If the "Show XML Request/Response" checkbox is checked than the XML Request that can be used to generate the XML Response is also shown.

Since Version 6, there are 2 types of XML Response/Response structures: V1 (short for Version 1) and V1 (short for Version 2).

Version 1 of the XML Request/Response Structure is the one used by the XML Service. With the XML Service, you do a HTTP POST of the XML Request to a URL and then read the XML Response. However when we implemented out SOAP Service (together with the WSDL), the Version 1 XML turned out to be too complex and hindered Web Services interoperability. So a simpler structure was created: the Version 2 XML Request/Response Structure. The Version 2 is used for the Web Services/SOAP access to run Containers and described in the WSDL.

To view the actual Connector Requests, you can check the "Show the Trace" checkbox. This will display the requests and their responses

A Sample Run of the container produces results similar to the ones shown below:

 
   
 
© 2006, SAGA D.C. GmbH - All rights reserved

Powered by SAGA.M31 - Galaxy -