Changes between Initial Version and Version 1 of net.sf.basedb.opengrid/using

Timestamp:

Jan 12, 2017, 12:03:09 PM (8 years ago)

Author:

Nicklas Nordborg

Comment:

Started to write the "How to use" documentation

net.sf.basedb.opengrid/using

@@ +1 @@
+= How to use the Open Grid Scheduler package API =
+
+In this document 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. 
+
+== Enumerating Open Grid Clusters ==
+
+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 cluster that has been defined in the `opengrid-config.xml` file. The service is a singleton instance. Use the `OpenGridService.getInstance()` method to get the object. Note! It is important that the service is actually running inside BASE. Check the '''Administrate->Services''' page that this is the case.
+
+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 the 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 (extra) information that we want to return
+// Use JSONOptions.DEFAULT to only return the minimal information
+JSONOptions options = new JSONOptions();
+options.enable(JSONOption.CLUSTER_INFO);
+options.enable(JSONOption.NODE_INFO);
+
+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 <select> list
+var list = document.getElementById('cluster-list');
+list.length = 0;
+
+var clusters = response; // Response contains an array with cluster information
+for (var i = 0; i < clusters.length; i++)
+{
+   var cluster = clusters[i];
+   var option = new Option(cluster.connection.name, cluster.id);
+   option.cluster = cluster;
+   list[list.length] = option;
+}
+}}}
+
+Note that there is no need to use the `OpenGridCluster.connect()` method yet.
+
+== Creating a job script ==
+
+== Submitting a job ==
+
+== Getting notified when a job completes ==
+
+== Aborting jobs ==
+
+== Advanced usage ==
+