GridServer COM Integration Tutorial

Joel

Sujets

• Tutoriel
• Stringin' Along with Chet Atkins
• Visual Basic
• Logiciel propriétaire
• Manager de l'année (Ligue majeure de baseball)
• SdKfz 250

Informations

• Publié par: Misheg
• Nombre de lectures: 115
• Langue: English

Extrait

GridServer COM Integration Tutorial Version 4.2

The GridServer Developers Series Proprietary and Confidential

Confidentiality and Disclaimer

Neither this document nor any of its contents may be used or disclosed without the express written consent of DataSynapse. This document does not carry any right of publication or disclosure to any other party. While the information provided herein is believed to be accurate and reliable, DataSynapse makes no representations or warranties, express or implied, as to the accuracy or completeness of such information. Only those representations and warranties contained in a definitive license agreement shall have any legal effect. In furnishing this document, DataSynapse reserves the right to amend or replace it at any time and undertakes no obligation to provide the recipient with access to any additional information. Nothing contained within this document is or should be relied upon as a promise or representation as to the future. This product includes software developed by the Apache Software Foundation ( www.apache.org/ ). This product includes software developed by the OpenSSL Project for use in the OpenSSL Toolkit. ( www.openssl.org/ ). This product includes code licensed from RSA Data Security ( java.sun.com/products/jsse/LICENSE.html ). DataSynapse GridServer COM Integration Tutorial Version 4.2   Copyright © 2005 DataSynapse, Inc. All Rights Reserved. GridServer® is a registered trademark, DataSynapse, the DataSynapse logo, LiveCluster, and GridClient are trademarks, and GRIDesign is a servicemark of DataSynapse, Inc.   Protected by U.S. Patent No. 6,757,730. Other patents pending. WebSphere® is a registered trademark and CloudScape is a trademark of International Business Machines Corporation in the United States, other countries, or both. All other product names are trademarks or registered trademarks of their respective companies. DataSynapse, Inc. 632 Broadway, 5th Floor; New York, NY 10012   Tel: [phone] Fax: [phone]   Email: [e-mail]   Web: www.datasynapse.com For technical support issues and product updates, please visit customer.datasynapse.com . We appreciate any comments or suggestions you may have about this manual or other DataSynapse documentation. Please send your feedback to [e-mail] . 04220102105  

 Chapter 1  Introduction            

This guide is your reference for developing COM applications that utilize GridServer installations. It is divided into several sections covering the fundamentals of how to use the GridServer COM API.

Before you begin This guide assumes that you already have a GridServer Manager running and know the hostname, username, and password. If this isnt true, see the GridServer Installation Guide or contact your administrator.

GridServer 4.2 Documentation Roadmap The following documentation is available for GridServer 4.2:

GridServer Guides Four guides and four tutorials are included with GridServer in Adobe Acrobat (PDF) format. They are also available in print format. To view the guides, log in to the Administration tool, select the Admin tab, go to the Documentation page, and select a guide. A search engine is also available on this page for you to search all of the documentation for a phrase or keywords. The PDF files can also be found on the Manager at livecluster/admin/docs . The following guides are available: Introducing the GridServer Platform Series: Introducing the GridServer Platform Contains an introduction to GridServer , including definitions of key concepts and terms, such as work, Engines, Directors, and Brokers. This should be read first if you are new to GridServer . The GridServer Administration Series: GridServer Administration Guide Covers the operation of a GridServer installation as relevant to a system administrator. It includes basic theory on scheduling, fault-tolerance, failover, and other concepts, plus howto information, and performance and tuning information. Covers installation of GridServer for Windows and Unix, including Managers, Engines, and pre-installation planning.

GridServer Installation Guide

      GridServer COM Integration Tutorial  3  

GridServer 4.2 Documentation Roadmap

The GridServer Developer Series: GridServer Developers Guide Contains information on how to develop applications for GridServer , including information on using Services, PDriver (the Batch-oriented GridServer Client), the theory behind development with the GridServer Tasklet API and concepts needed to write and adapt applications. GridServer Object-Oriented Integration Tutorial on developing applications for GridServer using Tutorial the object-oriented Tasklet API in Java or C++. GridServer Service-Oriented Integration Tutorial on developing applications for GridServer using Tutorial Services, such as Java, .NET, native, or binary executable Services. GridServer PDriver Tutorial Tutorial on using PDriver, the Parametric Service Driver, to create and run Services with GridServer . GridServer COM Tutorial Tutorial explaining how client applications in Windows can use COMDriver, GridServer s COM API, to work with services on GridServer .

Other Documentation and Help In addition to the GridServer guides, you can also find help and information from the following sources: GridServer Administration Tool Help Context-sensitive help is available throughout the GridServer Administration Tool by clicking the help icon located on any page. This provides reference help, plus how- to topics. API Reference Reference information for the GridServer API is provided in the GridServer SDK in the docs   directory. The Java API information is in JavaDoc format, while C++ documentation is presented in HTML, and .NET API help is in HTMLHelp. You can also view and search them from the GridServer Administration Tool; log in to the Administration Tool, click the Admin tab, and select the Documentation   link. Knowledge Base A searchable archive of known issues and support articles is available online. To access the DataSynapse Knowledge Base, go to the DataSynapse customer extranet site at customer.datasynapse.com and log in. You can also use this site to file an issue report, download product updates and licenses, and view documentation.

     4    Chapter 1  Introduction    

This Document is Proprietary and Confidental

Document Conventions Convention Explanation Example italics Book titles The GridServer Developers Guide describes this API in detail. Text in quotation References to chapter or section See Preliminaries. marks titles bold text Emphasizes key terminology   Client applications ( Drivers ) submit work to a   central Manager . Enter your URL in the Address box and click Interface labels or options Next . Courier New User input, directories, file names, Run the script in the /opt/datasynapse   file contents, and program scripts directory. Blue text Hypertext link. Click to jump to the See the GridServer Developers Guide for specified page or document. details. [GS Manager Root] The directory where GridServer is The Driver packages are located in   installed, such as c:\datasynapse   [GS Manager or   Root]/webapps/livecluster/WEB- /opt/datasynapse . INF/driverInstall

 

GridServer COM Integration Tutorial

      5   

6

             

 

Chapter 1  Introduction

Document Conventions

This Document is Proprietary and Confidental

 Chapter 2  Using a Visual Basic Client and Java Service            

Introduction

In this chapter, we will demonstrate how to access a Service from a client application written in Visual Basic, using COMDriver. The example shows how the VB client can call COMDriver APIs to create and destroy a Service instance, execute the Service synchronously or asynchronously, and update the state of the Service. Although the Service in this example is a Java Service, client applications using COMDriver can access Services written in any server-side compatible language, provided that Service methods use strings for arguments and return values.

Getting Started

Installing the GridServer SDK Before you begin, you should download and install the GridServer SDK, which is available from your Manager in the GridServer Administration Tool. The SDK includes the COMDriver. For more information on installing the SDK, see Driver Installation on page 41 of the GridServer Installation Guide . Also make sure to download a copy of the driver.properties file as described in the instructions.

Setting up the Service The Service in this example simulates a simple calculator, with functions for the four operators, plus a memory function.   The Java source code is available in the GridServer SDK, in /GridServerSDK-win32/examples/service/calculator/service/java/ . The JavaCalculator class has a floating-point field called memory , and the following methods:  add , subtract , multiply , divide  each takes two strings representing floating-point numbers, and returns a string representing the result of the arithmetic operation.  addToMemory  takes in one string argument representing a floating-point number, and stores the sum of the input and memory   values back in memory .  setMemory  takes in one string argument representing a floating-point number and sets the memory field equal to it.  getMemory  takes in a string argument, and returns the value of memory . (The argument is unused, but is required by the Services API.)

     GridServer COM Integration Tutorial  7  

Client-side Code

Before the client can access the Service, we have to register a Service Type and deploy the Service resources. Make sure the Service Type is registered under the name JavaCalculatorExample in the GridServer Service Type Registry; this is how we will reference the Service from the client. The Service is automatically registered when GridServer is installed. To ensure that the calculator code has have been deployed to the Engines, navigate to the Resource Deployment page in the GridServer Administration Tool, and check that a JAR file named calculator.jar is present under the resources/shared/jar/ directory. If the code has not been deployed, build the JAR file from GridServerSDK- win32/examples/service/calculator/ by running buildJava.bat . Then upload the JAR file to GridServer from the subdirectory /calculator/work/jars . To find out more about writing, registering, and deploying a Service, refer to the GridServer Service-Oriented Integration Tutorial .

Referencing COMDriver in the Visual Basic Editor The COMDriver library has to be referenced in the Visual Basic client application. With the client application opened in Microsoft Visual Basic Editor, go to the References dialog box. Make sure that the reference to DataSynapse Driver 1.0 Type Library is checked. It should be referenced to [COMDriver installation]\DSCOMDriver.exe .

Client-side Code Now that the Service has been registered and deployed, we can access it from the client through COMDriver. Lets start by creating an instance of the Service.

Creating a Service Instance To create an instance of the Service JavaCalculatorExample using COMDriver, use the createService function in the DSCOMDRIVERLib package. Example 2.1: Creating a Service Instance Dim csfactory As New DSCOMDRIVERLib.ServiceFactory Dim service As DSCOMDRIVERLib.service Set service = csfactory.createService("JavaCalculatorExample", "0", Nothing, Nothing)

The first line creates an instance of ServiceFactory . This is used to create GridServer Service instances. ServiceFactory is defined in the DSCOMDRIVERLib library, which resolves in DSCOMDriver.exe . The second line declares a variable called service that will hold the Service instance. This variable should be visible to any other part of the code that wishes to interface with the Service. You will see that the rest of the code in this chapter references this variable. The third line calls the createService   method, which takes four arguments:  serviceName  The name of the registered Service (String).

      8       Chapter 2  Using a Visual Basic Client and Java This Document is Proprietary and Confidental  

 initData  The state initializing data for the Service (String).  options  Service options; see the Options class in the Service JavaDoc for available options.  description  Service descriptions; see the Description class in the Service Javadoc for available description options. The third and fourth arguments are of type Properties , which is a set of name-value pairs. Consult the COMDriver documentation for details. The method returns the created Service interface. In our example, an instance of the JavaCalculatorExample Service is initialized with the value 0 , with no options and description. If the supplied Service name is not registered on GridServer, the application will fail with a runtime error: Service: servicename .csdd not found .

Submitting Requests Synchronously Work requests can be submitted to a Service synchronously or asynchronously. We will go through submitting a request synchronously first. Depending on the number of input arguments you have for the Service function, you would use the execute or executeWithArray function. Both execute   functions take in three arguments: 1. methodName  the name of the method to invoke. 2. data  the input data.  3. discriminator    the discriminator used for this request; discriminators are discussed in later section in this chapter. Both return the output data as a string. The input and output arguments are restricted to strings, for reasons of network serialization, and better interoperability between clients and Services of different languages. The only difference between the two functions is that executeWithArray accepts an array of strings as the input data argument, whereas execute accepts a single string. For example: Example 2.2: Submitting Synchronous Requests Dim numInMemory As String numInMemory = service.execute("getMemory", "", Nothing) Dim sum As String Dim args(1) As String args(0) = "25" args(1) = "75" sum = service.executeWithArray("add", args, Nothing)

      GridServer COM Integration Tutorial  9   

Client-side Code

If the Engine-side function being executed takes one or no arguments, it is more convenient to use execute ; otherwise, place your arguments in an array, and pass them into executeWithArray . If the function takes no arguments, like the getMemory function, use execute with an empty string. The execute functions do not return until the Service completes the request and returns the result. To have the function return immediately, use the submit function to submit requests asynchronously, as described below.

Submitting Requests Asynchronously To submit requests to the Service asynchronously, use the submit functions. They follow the same format as execute . One of the two functions will be more suitable depending on the number of input arguments the Service function takes: submit for zero or one argument, and submitWithArray for more than one argument. The submit functions return immediately, with the invocation ID (a Long integer) as the output argument. The ID increments sequentially and starts at 0; it can be used to identify results when are they later collected. Example 2.3: Submitting Asynchronous Requests Dim ID1 As Long ID1 = service.submit ("getMemory ", "", Nothing) Dim ID2 As Long Dim args(1) As String args(0) = "25" args(1) = "75" ID2 = service.submitWithArray("add", args, Nothing)

The results are collected by calling the collectNext function.

Collecting Results During Asynchronous Execution Since Visual Basic is not multithreaded, there are no callbacks for results collection. The collectNext function is used for collecting results during asynchronous calls. The function returns one of the available results from the Service; if none are available, it waits for the number of milliseconds supplied as an input argument before returning. The timeout prevents a client application from waiting indefinitely on a Service. collectNext returns the result as a ServiceData type, which includes the following properties:  Id  The Service invocation ID, which can be used to match the result with the corresponding submission.  IsError  A Boolean that signifies whether the execution resulted in an error; if so, the data property contains the error message.  Data  The result (Service function return value or error). For the same reason as execution and submit functions, all output arguments are pure strings.

     10   Chapter 2  Using a Visual Basic Client and Java This Document is Proprietary and Confidental  

To make collecting multiple results easier, the InvocationCount parameter of a Service is equal to the number of outstanding invocations. The following code demonstrates how one would implement results collection. It repeatedly checks a Service for available results. If there are results, one result is collected; the code checks to see if the result is an error, and prints out the result data accordingly. If there are no results, it waits for 1 second, and then loops. The loop ends when all the results have been collected. Example 2.4: Collecting Asynchronous Results While service.InvocationCount > 0 Dim sd As ServiceData Set sd = service.collectNext(1000) If Not sd Is Nothing Then If sd.IsError Then Debug.Print "collected " & sd.Id & " error: " & sd.Data Else Debug.Print "collected " & sd.Id & ": " & sd.Data End If End If Wend Debug.Print "done collecting"

Stateful Service Operations To better understand how to manage state from the client side, we will take a quick look at how Services on GridServer manage it. Lets consider our JavaCalculatorExample Service. The state maintained by the Service is a field called memory. There are two methods that are responsible for updating the state:  addToMemory  setMemory Although both methods update the state, GridServer has to handle them differently to ensure that the state is properly maintained. addToMemory refers to the previous value of memory , whereas setMemory does not. GridServer denotes the first type of method as an appendStateMethod , and the second type setStateMethod . When a Service instance is created on an Engine, the Engine will replay all state-changing methods from the last setStateMethod , or from the beginning if there have been no setStateMethods . Depending on the duration of the request, it may be worthwhile to follow appendStateMethods with setStateMethods periodically, to save memory on the Manager. These special state-changing methods have to be identified when the Service is registered in GridServer. Within the Service configuration of the JavaCalculatorExample , under the section ContainerBinding , these method names should be included in the fields titled appendStateMethods and setStateMethods . Once the methods have been registered on the Service, a client can only access them through the updateState functions. These functions behave in a similar way to execute functions. They take three input arguments:  methodName  the name of the method to invoke;

     GridServer COM Integration Tutorial  11  