= How to use the Open Grid Scheduler package API = In this tutorial we will try to describe the main aspects of the programmatic API that other extensions can use in order to access and use Open Grid Clusters. [[PageOutline(2-3,,inline,numbered)]] See also the [/chrome/site/net.sf.basedb.opengrid/api/index.html Javadoc API] documentation. == The use case == The use case in this tutorial is that we are going to implement an extension that wants to display a web page inside BASE for starting a job on an Open Grid Cluster. We will concentrate on the Open Grid part of this and will not care about how the extension interacts with BASE. You may want to read more about this in the [http://base.thep.lu.se/chrome/site/latest/html/developer/extensions/index.html BASE documentation]. We will assume that you have been able to display a web page which allows the user to select input parameters for the job. On this web page you also want the user to be able to select an Open Grid Cluster that the job should be submitted to. The list below is an overview of the main steps that are needed. 1. Display a selection list with available Open Grid Clusters 2. The web page submits the information to a servlet 3. The servlet creates a job script and submit it to the cluster 4. When the job is completed we want to get a notification so that we can import files and other data back into BASE == Enumerating Open Grid Clusters == In this step we want to display a simple selection list on the web page that allows the user to select a pre-defined Open Grid Cluster. We recommend that the list is populated by !JavaScript code which uses AJAX, a servlet and JSON to retreive the information. You'll need to implement all of this in your own extension package. The `OpenGridService` class is typically the starting point for a lot of actions. From this class it is possible to get information about and access all clusters that have been defined in the `opengrid-config.xml` file. The service is a singleton, use the `OpenGridService.getInstance()` method to get the instance. Note! It is important that the service is actually running inside BASE. Check the '''Administrate->Services''' page that this is the case, otherwise you will get an empty service. To enumerate the available Open Grid Clusters use one of the `OpenGridService.getClusters()` methods. This will return a collection of `OpenGridCluster` instances. Most methods in this class are used for getting configuration information from the `opengrid-config.xml` file. The `OpenGridCluster.getId()` method returns the internal ID of the cluster definition. It is created by combining the username, address and port of the cluster (for example, `griduser@grid.example.com:22`). The ID can then be used with `OpenGridService.getClusterById()` to directly access the same cluster later on. Other useful information can be found in the objects returned by calling `OpenGridCluster.getConnectionInfo()` and `OpenGridCluster.getConfig()`. The `OpenGridCluster.asJSONObject()` contains more or less the same information wrapped up as JSON data. This is useful for transferring information a web interface to allow a user to select a cluster to work with. '''Java code in a servlet running on the BASE web server''' {{{ DbControl dc = ... // We need an open DbControl from BASE // Options specifying which information that we want to return // Use JSONOptions.DEFAULT to only return the minimal information JSONOptions options = JSONOptions.DEFAULT; OpenGridService service = OpenGridService.getInstance(); JSONArray jsonHosts = new JSONArray(); // Enumerates all clusters that the current user has access to for (OpenGridCluster host : service.getClusters(dc, Include.ALL)) { jsonHosts.add(host.asJSONObject(options)); } return jsonHosts; // This is what we transfer to the web client via AJAX }}} '''!JavaScript code running in the web browser the current user is using''' {{{ // In the web client use the JSON data to populate a