Progress DataDirect OpenAccess REST IP Generator User's Guide. Release 7.2

Transcription

1 Progress DataDirect OpenAccess REST IP Generator User's Guide Release 7.2

2

3 Notices For details, see the following topics: Copyright Copyright 2014 Progress Software Corporation. All rights reserved. These materials and all Progress software products are copyrighted and all rights are reserved by Progress Software Corporation. The information in these materials is subject to change without notice, and Progress Software Corporation assumes no responsibility for any errors that may appear therein. The references in these materials to specific platforms supported are subject to change. Business Making Progress, Corticon, DataDirect (and design), DataDirect Cloud, DataDirect Connect, DataDirect Connect64, DataDirect XML Converters, DataDirect XQuery, Fathom, Making Software Work Together, OpenEdge, Powered by Progress, Progress, Progress Control Tower, Progress OpenEdge, Progress RPM, Progress Software Business Making Progress, Progress Software Developers Network, Rollbase, RulesCloud, RulesWorld, SequeLink, SpeedScript, Stylus Studio, and WebSpeed are registered trademarks of Progress Software Corporation or one of its affiliates or subsidiaries in the U.S. and/or other countries. AccelEvent, AppsAlive, AppServer, BusinessEdge, Progress Easyl, DataDirect Spy, DataDirect SupportLink, Easyl, Future Proof, High Performance Integration, OpenAccess, Pacific, ProDataSet, Progress Arcade, Progress Pacific, Progress Profiles, Progress Results, Progress RFID, Progress Responsive Process Management, Progress Software, ProVision, PSE Pro, SectorAlliance, SmartBrowser, SmartComponent, SmartDataBrowser, SmartDataObjects, SmartDataView, SmartDialog, SmartFolder, SmartFrame, SmartObjects, SmartPanel, SmartQuery, SmartViewer, SmartWindow, WebClient, and Who Makes Progress are trademarks or service marks of Progress Software Corporation and/or its subsidiaries or affiliates in the U.S. and other countries. Java is a registered trademark of Oracle and/or its affiliates. Any other marks contained herein may be trademarks of their respective owners. 3

4 Notices 4

5 Table of Contents Preface...7 Purpose...7 Audience...7 Typographical Conventions...8 Contacting Customer Support...9 Chapter 1: Prerequisites...11 Software Requirements...11 Chapter 2: Product Installation...13 Installing OpenAccess SDK Server and Client...13 Installing OpenAccess REST IP Generator...13 Connecting to the Sample REST Source...14 Chapter 3: Developing Interface Provider for REST Data Source...19 Defining Data Source Properties...19 Defining Data Source Schema...20 XML Schema Format...21 General Table Information...21 Column Information...21 Index Information...22 Relationship Information...23 Generating IP Template Code...25 Customizing IP Code...30 Chapter 4: Configuring OpenAccess for a REST Data Source...31 Creating a Service on OpenAccess Server...31 Chapter 5: Tutorial...33 Generating Marvel Driver...33 Customizing Marvel Driver...39 Index

6 6

7 Preface For details, see the following topics: Purpose Audience Typographical Conventions Contacting Customer Support Purpose Progress DataDirect OpenAccess REST IP Generator is a framework that enables you to build a driver for any REST data source quickly and easily. The current version supports building a read-only driver. The framework generates OpenAccess Interface Provider (IP) template source code for a REST data source based on metadata information that you provide, that is, data source information and schema information. Audience This guide is intended for developers who want to build drivers for REST data sources. It helps you understand how to use the OpenAccess REST IP Generator to generate template IP source code and to deploy an OpenAccess service for a REST data source. 7

8 Preface Typographical Conventions This guide uses the following typographical conventions: italics Convention Explanation Introduces new terms with which you may not be familiar, and is used occasionally for emphasis. bold Emphasizes important information. Also indicates button, menu, and icon names on which you can act. For example, click Next. BOLD UPPERCASE Indicates keys or key combinations that you can use. For example, press the ENTER key. UPPERCASE Indicates SQL reserved words. monospace Indicates syntax examples, values that you specify, or results that you receive. monospaced italics > Indicates names that are placeholders for values that you specify. For example, filename. Separates menus and their associated commands. For example, Select File > Copy means that you should select Copy from the File menu. / The slash also separates directory levels when specifying locations under UNIX. vertical rule Indicates an "OR" separator used to delineate items. brackets [ ] Indicates optional items. For example, in the following statement: SELECT [DISTINCT], DISTINCT is an optional keyword. Also indicates sections of the Windows Registry. braces { } Indicates that you must select one item. For example, {yes no} means that you must specify either yes or no. ellipsis... Indicates that the immediately preceding item can be repeated any number of times in succession. An ellipsis following a closing bracket indicates that all information in that unit can be repeated. 8

9 Preface Contacting Customer Support Progress DataDirect offers a variety of options to meet your customer support needs. Please visit our Web site for more details and for contact information: The Progress DataDirect Web site provides the latest support information through our global service network. The SupportLink program provides access to support contact details, tools, patches, and valuable information, including a list of FAQs for each product. In addition, you can search our Knowledgebase for technical bulletins and other information. When you contact us for assistance, please provide the following information: Your customer number or the serial number that corresponds to the product for which you are seeking support, or a case number if you have been provided one for your issue. If you do not have a SupportLink contract, the SupportLink representative assisting you will connect you with our Sales team. Your name, phone number, address, and organization. For a first-time call, you may be asked for full customer information, including location. The Progress DataDirect product and the version that you are using. The type and version of the operating system where you have installed your product. Any database, database version, third-party software, or other environment information required to understand the problem. A brief description of the problem, including, but not limited to, any error messages you have received, what steps you followed prior to the initial occurrence of the problem, any trace logs capturing the issue, and so on. Depending on the complexity of the problem, you may be asked to submit an example or reproducible application so that the issue can be re-created. A description of what you have attempted to resolve the issue. If you have researched your issue on Web search engines, our Knowledgebase, or have tested additional configurations, applications, or other vendor products, you will want to carefully note everything you have already attempted. A simple assessment of how the severity of the issue is impacting your organization. 9

10 Preface 10

11 1 Prerequisites The following section describes prerequisites for using the OpenAccess REST IP Generator. For details, see the following topics: Software Requirements Software Requirements JDK or higher JRE 6 or higher Progress DataDirect OpenAccess SDK 7.2 Progress DataDirect OpenAccess JDBC/ODBC client 11

12 Chapter 1: Prerequisites 12

13 2 Product Installation This section describes how to install Progress DataDirect OpenAccess REST IP Generator. For details, see the following topics: Installing OpenAccess SDK Server and Client Installing OpenAccess REST IP Generator Connecting to the Sample REST Source Installing OpenAccess SDK Server and Client From the Progress Website, download and install OpenAccess SDK 7.2 (OpenAccess Server) and OpenAccess Client (ODBC /JDBC). Refer to the Progress DataDirect OpenAccess Installation Guide for instructions. Installing OpenAccess REST IP Generator The following procedure helps you install the OpenAccess REST IP Generator. To install OpenAccess REST IP Generator: 13

14 Chapter 2: Product Installation 1. Copy the distributed oa_rest_ip_generator_7_2_0.jar file into the following location: [OpenAccess-Install-Dir]\Program Files\Progress\DataDirect\oaserver72. For example, C:\Program Files\Progress\DataDirect\oaserver At the command prompt at location[openacces-install-dir]\program Files\Progress\DataDirect\oaserver72, execute the following command: jar xvf oa_rest_ip_generator_7_2_0.jar For example, C:\Program Files\Progress\DataDirect\oaserver72\jar xvf oa_rest_ip_generator_7_2_0.jar. This generates a RestGenerator directory at the following location: [OpenAccess-Install-Dir]:\Program Files\Progress\DataDirect\oaserver72\ip. The RestGenerator directory consists of the following directories and files: lib:this directory contains library files that the OpenAccess REST IP Generator uses. tools/service_setup: This directory contains the batch files that are used to create or delete OpenAccess services for REST data sources. sample: This directory contains a sample application and a sample schema for Marvel Comics ( input.props: This file contains properties that you must set to use the OpenAccess REST IP Generator. Oarestipgen.jar: The OpenAccess REST IP Generator tool. Connecting to the Sample REST Source A sample driver is created for you at: [OpenAccess-Install-Dir]:\Program Files\Progress\DataDirect\oaserver72\ip\RestGenerator\sample\Marvel. This sample helps you understand how to connect to Marvel, a REST data source. To execute the following procedure, you must register with Marvel to obtain the public and private keys. To register with Marvel, visit To connect to Marvel: 1. Go to the following location: 14

15 Connecting to the Sample REST Source [OpenAccess-Install-Dir]:\Program Files\Progress\ DataDirect\oaserver72\ip\RestGenerator\sample\Marvel\tools\service_setup and then edit the following variables in the oacreate_marvelservice.bat file (file name on UNIX: oacreate_marvelservice.sh). Table 1: oacreate_marvelservice.bat Attributes Variable Name USERNAME OASERVER Values/Path [OpenAccess-Install-Dir]\ Program Files\Progress\DataDirect\ oaserver72 Description When OpenAccess Agent is running as ServiceAdminAuthMethods =OSLogon(UID,PWD), you must enter the username. The OpenAccess server path. JVMLOCATION [Java-Install-Dir]\Program Files\Java\jdk1.6.0_45\jre\bin\ server The Java installation directory. SERVICE_PORT OA_DATASOURCE DATASOURCEIPCLASS RESOURCE_PROPERTIES Marvel com/ddtek/common/ip/restip %OASERVER%/ip/RestGenerator/ sample/%oa_datasource%/schema The service port number. The OpenAccess data source name. The data source IP class path, that is, the base package. The XML schema path. 2. At the command prompt at location [OpenAccess-Install-Dir]\Program Files\Progress\DataDirect\oaserver72\ip\RestGenerator\sample\Marvel\tools\service_setup execute the following command: oacreate_marvelservice.bat For example: C:\Program Files\Progress\DataDirect\oaserver72\ip\RestGenerator\ sample\marvel\tools\service_setup\oacreate_marvelservice.bat. This creates MarvelService on the OpenAccess server. 3. Start the MarvelService. You can start the MarvelService using the command prompt on Windows or using the Progress Datadirect OpenAccess SDK 7.2 Management Console. The procedures for using the command prompt and the management console are described below. Using the command prompt on Windows: 15

16 Chapter 2: Product Installation At the command prompt, execute the following command: net start MarvelService For example, C:\> net start MarvelService. Note:Command to start the service can be executed from any path. Using Progress Datadirect OpenAccess SDK 7.2 Management Console To start the service using the Management Console: 1. Open Progress Datadirect OpenAccess SDK 7.2 Management Console. 2. On the left pane, go to Manager>Connected to OpenAccessSDK720_Agent>Services>MarvelService. 3. Right-click MarvelService; then click "Start MarvelService". MarvelService starts. This starts MarvelService on the OpenAccess server. You can go to the OpenAccess SDK Management Console to check if MarvelService has started. Optionally, in the Management Console, you can specify the public key and private key of Marvel.com so that you do not have to enter the keys each time you try to connect to Marvel. To specify the public key and private key in the Management Console: 1. In the left pane of the Management Console, click MarvelService>Data Source Settings>Marvel>IP Parameters. 2. In the right pane of the Management Console, double-click DataSourceIPCustomProperties. The DataSourceIPCustomProperties Properties window appears. 3. In the Value field, enter the values for public and private keys. 4. Connect to and fetch data from Marvel. Connecting to Marvel Using ODBC Client: 16

17 Connecting to the Sample REST Source To connect to Marvel using the ODBC client: 1. Go to Control Panel>Administrative Tools and then double-click Data Sources (ODBC). The ODBC Data Source Administrator window appears. 2. On the User DSN tab, click ADD. The Create New Data Source window appears. 3. On the Create New Data Source window, select DataDirect OpenAccess SDK 7.2; and then click Finish. The DataDirect OpenAccess SDK ODBC Driver Setup window appears. 4. On the DataDirect OpenAccess SDK ODBC Driver Setup window, enter the values for the following fields: Data Source Name: The data source name. For example, Marvel. Service Host: The service host. For example, localhost. Service Port: The port at which the service is available. For example, Service Data Source: The name of the service data source that is active on the OpenAccess server. For example, Marvel. Custom Properties: The custom properties required to connect to the Marvel data source, mainly the public key and the private key. Syntax: publickey=<public_key>; privatekey=<private_key> 5. Click Test Connect; and then click OK. The Connection test was successful. message appears. If you receive an error,check whether the service is running and if you have entered the correct values for the fields mentioned above. 6. Click Apply and then click OK twice. 7. At the command prompt at location[openaccess-odbc-client]:\program Files\Progress\DataDirect\oaodbc72, execute the following command: odbcisql.exe For example, C:\Program Files\Progress\DataDirect\oaodbc72\odbcisql.exe. The ISQL> prompt appears. 8. At the ISQL> prompt, execute the following command: connect Marvel. A connection is established with Marvel. 9. Execute an SQL query for obtaining data from the Marvel database. For example: SELECT * FROM comic WHERE ID=49015; SELECT TOP 10 * FROM comic; SELECT TOP 10 * FROM Creator; 17

18 Chapter 2: Product Installation The query fetches a result from the Marvel database and the result is displayed at the ISQL> prompt. Connecting to Marvel Using JDBC Client: To connect to Marvel using the JDBC client: 1. On your computer, go to [OAJDBCCLIENT-INSTALL-DIR]\testforjdbc. For example, C:\oajdbcclient\testforjdbc. 2. Double-click the testforjdbc.bat file. The Test for JDBC Tool window appears. 3. Click Press Here To Continue. 4. From the Connection menu, click Connect to DB... The Select A Database window appears. 5. In the Database field enter the following string: jdbc:openaccess://localhost:19992;serverdatasource=marvel; CustomProperties=(publickey=public_key;privatekey=private_key); then click Connect. The connection is established with Marvel and a connection window opens up. 6. On the newly opened window, go to Connection > Load and Go... The Get Load And Go SQL window appears. 7. In Type SQL Here, execute metadata queries to obtain table and column information. For example, type the following query: SELECT TOP 100 * FROM Comic. The data is fetched from the Comic table and records are displayed in the connection window. You have now successfully installed the product and connected to the Sample REST data source (Marvel Comics). You can now choose to either try the Tutorial on page 33 which provides a walkthrough of how to build the Interface Provider for Marvel or go to the next section to learn how to build the Interface Provider for any REST source. 18

19 Developing Interface Provider for REST Data Source 3 To develop an Interface Provider (IP) for a REST data source, the user must run the OpenAccess Rest IP Generator tool to generate the template IP code and then complete the IP implementation. However, before running the OpenAccess REST IP Generator, you must prepare the following artifacts. Data Source Properties Data Source Schema These artifacts are described next. For details, see the following topics: Defining Data Source Properties Defining Data Source Schema Generating IP Template Code Customizing IP Code Defining Data Source Properties You must define the data source properties in the input.props file located at: [OpenAccess-Install-Dir]\Program Files\Progress\DataDirect\oaserver72\ip\RestGenerator. 19

20 Chapter 3: Developing Interface Provider for REST Data Source Note: You can change the name of input.props file per your convenience. The file contains the following properties for which you have to enter values: Table 2: input.props Properties Property DATABASE_NAME CATALOG_NAME SCHEMA_NAME DATABASE_VERSION SCHEMA_LOCATION SCHEMA_TYPE PATHTOWRITE BASEPACKAGE DATASOURCE BASE_URL The database name. The catalog name. The schema name. The version number. Description The XML schema location that is used as an input for the OpenAccess REST IP Generator. The type of schema. For example XML. The location to which OpenAccess REST IP Generator writes the generated files. The base package. For example, if BASEPACKAGE=com.ddtek, the generated source code will have com\ddtek as the base package. The data source name. For example, Marvel. The base URL. For example, DATABASE_NAME, CATALOG_NAME, SCHEMA_NAME, and DATABASE_VERSION are used in connection metadata. Defining Data Source Schema The OpenAccess REST IP Generator uses the XML schema defined by you to generate the template code. The following sections help you understand how to define the XML schema of a table that acts as input for the OpenAccess REST IP Generator. 20

21 Defining Data Source Schema XML Schema Format An XML schema file must contain the following information pertaining to a table. General table information Column information Index information Key information (Foreign Key/Primary Key) General Table Information Your schema must contain general table information, such as table name, table alias, and user, inside the <table> tag. For example, <table name="contact" alias="contact Table" userdata="user specific data"></table>. Column Information Your schema must contain column information, such as column name, column alias, and data type, inside the <column> tag. For example, <column name="portalid" columnalias="portal-id" datatype="4" userdata=""/>. The following is a list of column information attributes that is used while creating a table schema. Table 3: Column Information Attributes Attributes Description name columnalias datatype charmaxlength numericprecision typename numericscale nullable scope The column name of the table. The column name of the table as defined in the service. The data type of the column. The length, in bytes, of data that is to be transferred to the client in its default format. The maximum number of digits used by data in a column. The X/Open column type. The number of digits to the right of the decimal point. Specifies whether the column can be null. Scope of the SQL_BEST_ROWID column. 21

22 Chapter 3: Developing Interface Provider for REST Data Source Attributes Description userdata operatorsupport pseudocolumn columntype remarks Any proprietary data about the column that you want the IP to access. The IP calls dam_describecoldetail() to fetch this information. A place for the IP to maintain operators that it supports for conditions on a column (for example, =, >, LIKE), when the column is considered for a restriction or for a search condition Indicates whether the column is a pseudo column, such as Oracle ROWID. Defines the column type. The description of a column. Index Information Your schema must contain index information, such as index name, and index type, inside the <stat> tag. For example, <stat nonunique="0" indexname="idxcontactvid" indextype="1" seqinindex="1" columnname="vid" cardinality="-1"/>. The following is a list of index information attributes that is used while creating a table schema. Table 4: Index Information Attributes Attribute Description nonunique indexqualifier indexname Indicates whether the index prohibits duplicate values: TRUE (1) the index values can be non-unique. FALSE (0) the index values must be unique. NULL (empty) if type is SQL_TABLE_STAT. The name of the database to which the table belongs. The name of the index. This value must be NULL if type is SQL_TABLE_STAT. 22

23 Defining Data Source Schema Attribute Description indextype seqinindex columnname collation cardinality The type of information returned. Specify 1, 2, or 3 as the value for Microsoft Access to use the indexes. Valid values are: SQL_TABLE_STAT (0) a statistic for the table. SQL_INDEX_CLUSTERED (1) a clustered index. SQL_INDEX_HASHED (2) a hashed index. SQL_INDEX_OTHER (3) other type of index. The column sequence number in the index, starting with 1. Set to NULL if the index type is SQL_TABLE_STAT. This value is 1 if only one column defines the index. The column identifier. Set to NULL if type is SQL_TABLE_STAT. The collation sequence. Valid values are: A ascending. D descending. NULL if type is SQL_TABLE_STAT or if no collation occurs. The cardinality of the table or index. OpenAccess SDK SQL engine uses an optimal index if the value specified for this attribute is not a unique index. Valid values are: The number of rows in the table if type is SQL_TABLE_STAT. The number of unique values in the index if type is not SQL_TABLE_STAT. High cardinality indexes are preferred for query optimization. NULL if the value is not available from the data source. Relationship Information Your schema must contain relationship information, such as primary key name, and foreign key name, inside the <pkfk> tag. 23

24 Chapter 3: Developing Interface Provider for REST Data Source For example, <pkfk pkcolumnname="vid" keyseq="1" updaterule="-1" pkname="pkcontactvid" />. The following is a list of relationship information attributes that is used while creating a table schema. Table 5: Relationship Information Properties Attributes pktablequalifier pktableowner pktablename pkcolumnname fktablequalifier fktableowner fktablename fkcolumnname keyseq fkname pkname Description The name of the database that contains the primary key table. This parameter is used to distribute tables into physically different databases. Typically, set this field value to SCHEMA. To expose this field as an empty value and to return 0, when OAIP_getInfo(SQL_MAX_QUALIFIER_NAME) is called, set this field value to NULL. The owner of the primary key table. The name of the primary key table (how the end user refers to it). The name of the primary key column. The name of the database that contains the foreign key table. This parameter is used to distribute tables into physically different databases. Typically, set this field value to SCHEMA. The owner of the foreign key table. The name of the foreign key table (how the end user refers to it). The name of the foreign key column. The column sequence number in key, starting with 1. The foreign key identifier. The primary key identifier. 24

25 Generating IP Template Code The following code-snippet illustrates how to define XML schema of a table. <?xml version="1.0" encoding="utf-8"?> <tables> <table name="comic"> <column name="id" datatype="4" userdata=""/> <column name="digitalid" datatype="4" userdata=""/> <column name="title" datatype="-9" userdata=""/> <column name="issuenumber" datatype="8" userdata=""/> <column name="variantdescription" datatype="-9" /> <column name="description" datatype="-9" userdata=""/> <column name="modified" datatype="-9" userdata=""/> <column name="isbn" datatype="-9" userdata=""/> <column name="upc" datatype="-9" userdata=""/> <column name="diamondcode" datatype="-9" userdata=""/> <column name="ean" datatype="-9" userdata=""/> <column name="issn" datatype="-9" userdata=""/> <column name="format" datatype="-9" userdata=""/> <column name="pagecount" datatype="-9" userdata=""/> <column name="resourceuri" datatype="-9" userdata=""/> <stat nonunique="0" indexname="idxcomicid" indextype="1" seqinindex="1" columnname="id" cardinality="-1" pages="-1" filterconditions="" /> <pkfk pkcolumnname="id" keyseq="1" updaterule="-1" deleterule="-1" pkname="pkcomicid" /> </table> </tables> Note: You must create separate XML files in the above-mentioned format for each table. Generating IP Template Code To generate IP template code: At the command prompt at location [OpenAccess-Install-Dir]\Program Files\Progress\DataDirect\oaserver72\ip\RestGenerator execute the following command: java -jar oarestipgen.jar input.props For example, C:\Program Files\Progress\DataDirect\oaserver72\ ip\restgenerator\ java -jar oarestipgen.jar input.props. OpenAccess REST IP Generator generates the template driver source code in the directory as mentioned in the PATHTOWRITE key of the input.props file. For example, if the input.props file contains PATHTOWRITE=sample\src, a sample\src directory, which contains the driver source code, is generated inside the [OpenAccess-Install-Dir]\Program Files\Progress\DataDirect\oaserver72\ip\RestGenerator directory. 25

26 Chapter 3: Developing Interface Provider for REST Data Source The generated source directory contains two packages: [BASEPACKAGE]\common and [BASEPACKAGE]\[DATASOURCE]. If you define BASEPACKAGE=com.ddtek and DATASOURCE=Sample in the input.props file, the generated source directory will contain the following directory structure: com\ddtek\sample and com\ddtek\common. com\ddtek\sample is also called com.ddtek.sample package. The files under this package and its sub package contain data source specific code. Often, you will modify files present under com\ddtek\sample. The following table contains a list of files that you can modify in the com\ddtek\sample package. Table 6: Modifiable Files in the com\ddtek\sample Package Package Name com.ddtek.sample.connection File Name ConnectionHelper.java RequestProcessor.java Description Modify this file if you want to process custom properties, invoke a request while connection. Modify this file if you want to modify a request before an invocation. For example, while executing a query you can append query parameters or you can append authentication headers. com.ddtek.sample.dataprocessor [TableName]DataProcesor.java A file for each table is created in this package. For example, if the table name is named Contact, a file named ContactDataProcesor is generated by OpenAccess REST IP Generator. In general, you have to modify this file to specify a request URL, and for processing of JSON response. com.ddtek.sample.schema SchemaDataProcessor.java This file is used to invoke requests during connection time. For example, a request for dynamic schema information and authentication information can be invoked with the help of this file. com\ddtek\common is also called com.ddtek.common package. The files under this package and its sub package contain common (OpenAccess IP) code. 26

27 Generating IP Template Code The following table contains a list of files and their location that you can modify per your requirement. Typically, Changes are not required in these common package files. 27

28 Chapter 3: Developing Interface Provider for REST Data Source Table 7: Modifiable Files in the com\ddtek\common Package Package Name com.ddtek.common.connection com.ddtek.common.cxf.client com.ddtek.common. dataprocessor com.ddtek.common.executor com.ddtek.common.ip File Name Status.java CXFClient.java CompositeDataProcessor.java DataConverter.java DataProcessor.java HttpStatusCodeMapper.java FlowController.java QueryExecutor.java Request.java Response.java RestIP.java Description This file contains status messages. This file contains the code for invoking the REST API. This file is used to register the data processors. This file is used for converting data based on the data types. This is the abstract super class of all the data processors. It contains information common to all the data processors. This file contains HTTP status codes and the standard messages. This file invokes requests from the invocation list. This file contains information about SQL queries. It is used for creating an invocation list. This file contains information about Request. This file contains information about Response. This is the actual IP Class that implements the oajava.sql.ip interface. 28

29 Generating IP Template Code Package Name com.ddtek.common.schema File Name RestIPConstants.java RestIPHelper.java InvocationContext.java OAConditionInfo.java SessionContext.java StatementContext.java ColumnInfo.java PkFkInfo.java SchemaInfo.java StatsInfo.java TableInfo.java Description Constants are defined in this file. This helper class contains utility methods. Every invocation has an invocation context. This file contains context information about a request. This file contains information about where conditions are used in a query. All the connection level information is stored in this file. For every query, a StatementContext object is created. This file contains complete information about a query. Used to represent column information. Used to represent primary-key and foreign-key information. This is used to read schema information and to create schema objects, such as TableInfo, and ColumnInfo.. This file is used to represent the index information. This file is used to represent table information. 29

30 Chapter 3: Developing Interface Provider for REST Data Source Customizing IP Code You can customize data processors present at: [PATHTOWRITE]\[BASEPACKAGE]\[DATASOURCE]\dataprocessor. For example, if the input.props file contains PATHTOWRITE=restsample, BASEPACKAGE=com.ddtek, and DATASOURCE=SampleDataSource, data processors to be modified are in: C:\Program Files\Progress\DataDirect\oaserver72\ip\RestGenerator\restsample\com\ddtek\ sampledatasource\dataprocessor. In general, you only have to modify the files present at [PATHTOWRITE]\[BASEPACKAGE]\[DATASOURCE]. For more information on customizing the IP code, refer to Generating IP Template Code on page

31 4 Configuring OpenAccess for a REST Data Source The following section helps you understand how to configure OpenAccess for a REST data source. For details, see the following topics: Creating a Service on OpenAccess Server Creating a Service on OpenAccess Server The oacreate_restservice.bat file located at [Install-Dir]\Program Files\Progress\DataDirect\oaserver72\ip\RestGenerator\tools\service_setup is used to create a service on the OpenAccess server. To run this file, you must enter values for the following variables in the oacreate_restservice.bat file. Table 8: Required Variables and Values for the oacreate_restservice.bat File Variable Value USERNAME OASERVER JVMLOCATION The user name, if any is set for accessing the OpenAccess server. The OpenAccess server's location. The Java Virtual Machine's location. 31

32 Chapter 4: Configuring OpenAccess for a REST Data Source Variable SERVICEPORT OA_DATASOURCE DATASOURCEIPCLASS RESOURCE_PROPERTIES Value The port at which the OpenAccess service for the REST data source will be made available. The OpenAccess data source. The data source IP class. The schema location. The following code-snippet illustrates variable values for the oacreate_restservice.bat file. set USERNAME= set OASERVER=[Install-Dir]\Program Files\Progress\DataDirect\oaserver72 set JVMLOCATION=[Install-Dir]\Program Files\Java\jdk1.6.0_32\jre\bin\server set SERVICE_PORT=19992 set OA_DATASOURCE=Sample set DATASOURCEIPCLASS=com/ddtek/common/ip/RestIP set RESOURCE_PROPERTIES=%OA_SERVER%/ip/RestGenerator/schema Also, check the service JVM class path: ServiceJVMClassPath echo "saa" >> %OA_DATASOURCE%.ini echo "%OA_DATASOURCE%Service" >> %OA_DATASOURCE%.ini echo "ServiceJVMClassPath" >> %OA_DATASOURCE%.ini echo "%OASERVER%\ip\oajava\oasql.jar;%OASERVER%\ip\RestGenerator\%OA_DATASOURCE%\%OA_DATASOURCE%.jar" >> %OA_DATASOURCE%.ini To create a service on the OpenAccess server, at the command prompt execute the following command: oacreate_restservice.bat This creates an OpenAccess service on the OpenAccess server. 32

33 5 Tutorial This tutorial explains how to use the OpenAccess REST IP Generator to create a driver for Marvel. It is assumed that you have installed all the necessary software on your computer for using the OpenAccess REST IP Generator. In general, you must perform the following steps to create a REST Data Source driver: To create a REST Data Source Driver: 1. Update input.props. 2. Define the schema. 3. Generate the IP code. 4. Customize the generated IP code. 5. Build the source code. 6. Create an OpenAcess service. 7. Test the generated driver. For details, see the following topics: Generating Marvel Driver Customizing Marvel Driver Generating Marvel Driver To create a driver for Marvel: 33

34 Chapter 5: Tutorial 1. Update the input.props file as per the following instructions. In the input.props file located at: [OpenAccess- Install-Dir]\Program Files\Progress\DataDirect\oaserver72\ip\RestGenerator, enter the following property values. Table 9: Required Properties and Values for the input.props File Property Value DATABASE_NAME CATALOG_NAME SCHEMA_NAME DATABASE_VERSION SCHEMA_LOCATION SCHEMA_TYPE PATHTOWRITE BASEPACKAGE DATASOURCE BASE_URL Marvel MCATALOG Marvel 1.0 schema XML MarvelTest/src com.ddtek MarvelTest 2. Define the schema as per the following instructions. Copy the schema folder from RestGenerator\sample\Marvel\schema to the RestGenerator folder. This creates the RestGenerator\schema folder with the sample schema files comic.xml and creator.xml. 3. Generate the IP code as per the following instructions. At the command prompt at location [OpenAccess-Install-Dir]:\Program Files\Progress\DataDirect\oaserver72\ip\RestGenerator, execute the following command: java -jar oarestipgen.jar input.props For example, C:\Program Files\Progress\DataDirect\oaserver72\ip\RestGenerator\ java -jar oarestipgen.jar input.props. The MarvelTest\src folder is generated at: [OpenAccess-Install-Dir]:\Program Files\Progress\DataDirect\oaserver72\ip\RestGenerator. 4. Customize the generated IP code as per the following instructions. 34

35 Generating Marvel Driver Customize the files generated at [OpenAccess-Install-Dir]:\Program Files\Progress\DataDirect\oaserver72\ip\RestGenerator\MarvelTest\ com\ddtek\marveltest\dataprocessor and [OpenAccess-Install-Dir]:\Program Files\Progress\DataDirect\oaserver72\ip\RestGenerator\MarvelTest\ com\ddtek\marveltest\connection. For more information on customizing Marvel data processors and connection files, refer to Customizing Marvel Driver on page Build the source code as per the following steps. a) Edit the build.xml file as follows: <project basedir="." default="build" name="build-marvel-ds"> <property name="oa.location" value="c:\program Files\Progress\DataDirect\oaserver72"/> <property name="restgen.location" value="${oa.location}\ip\restgenerator" /> <property name="datasource" value="marveltest" /> <property name="datasource.location" value="${restgen.location}\${datasource}" /> <property environment="env" /> <property name="debuglevel" value="source,lines,vars" /> <property name="target" value="1.6" /> <property name="source" value="1.6" /> b) At the command prompt at location [OpenAccess-Install-Dir]:\Program Files\Progress\DataDirect\oaserver72\ip\ RestGenerator\tools, execute the following command: ANT For example, C:\Program Files\Progress\DataDirect\oaserver72\ip\RestGenerator\tools\ANT. The build.xml file is executed and a MarvelTest.jar file is created at C:\Program Files\Progress\DataDirect\oaserver72\ip\RestGenerator\MarvelTest. 6. Create the OpenAccess service as per the following steps. a) Enter the following values in oacreate_restservice.bat. This file is located at [OpenAccess-Install-Dir]\Program Files\Progress\DataDirect\oaserver72\ ip\restgenerator\tools\service_setup. Table 10: Required Values for the oacreate_restservice.bat File Variable Value USERNAME OASERVER JVMLOCATION SERVICE_PORT The user name. Set USERNAME, if OpenAccess Agent is running as ServiceAdminAuthMethods=OSLogon(UID,PWD). C:\Program Files\Progress\DataDirect\oaserver72 C:\Program Files\Java\jdk1.6.0_45\jre\bin\server

36 Chapter 5: Tutorial Variable Value OA_DATASOURCE DATASOURCEIPCLASS RESOURCE_PROPERTIES MarvelTest com/ddtek/common/ip/restip %OASERVER%/ip/RestGenerator/schema Also, edit the DataSourceIPCustomProperties setting: rem DataSourceIPCustomProperties echo "dsaa" >> %OA_DATASOURCE%.ini echo "%OA_DATASOURCE%Service" >> %OA_DATASOURCE%.ini echo "%OA_DATASOURCE%" >> %OA_DATASOURCE%.ini echo "DataSourceIPCustomProperties" >> %OA_DATASOURCE%.ini echo "privatekey=?;publickey=?" >> %OA_DATASOURCE%.ini b) Run the oacreate_restservice.bat script as per the following instructions. At the command prompt at location [Install-Dir]\Program Files\Progress\DataDirect\oaserver72\ip\RestGenerator\tools\service_setup, execute the following command: oacreate_restservice.bat For example, C:\Program Files\Progress\DataDirect\oaserver72\ip\RestGenerator\tools\service_setup\ oacreate_restservice.bat. A MarvelTestService is created on the OpenAccess server. 7. Start MarvelTestService. Using the Command Prompt on Windows: At the command prompt, execute the following command: net start MarvelTestService For example, C:\> net start MarvelTestService. This starts the MarvelTestService on the OpenAccess server. Using Progress DataDirect OpenAccess SDK 7.2 Management Console: To start the service using the Management Console: 1. Open Progress DataDirect OpenAccess SDK 7.2 Management Console. 2. On the left pane, go to Manager>Connected to OpenAccessSDK720_Agent>Services>MarvelTestService. 3. Right-click MarvelTestService and then click Start MarvelTestService. MarvelTestService starts. 8. Test the created Marvel driver as per the following instructions. To test the created driver, connect to Marvel and fetch data. You can connect to Marvel using the OpenAccess ODBC Client or using the OpenAccess JDBC client. The steps to establish a connection using these clients are described below. Connecting to Marvel using the OpenAccess ODBC Client: 36

37 Generating Marvel Driver 1. Go to Control Panel>Administrative Tools and then double-click Data Sources (ODBC). The ODBC Data Source Administrator window appears. 2. On the User DSN tab, click ADD. The Create New Data Source window appears. 3. On the Create New Data Source window, select DataDirect OpenAccess SDK 7.2 and then click Finish. The DataDirect OpenAccess SDK ODBC Driver Setup window appears. 4. On the DataDirect OpenAccess SDK ODBC Driver Setup window, enter appropriate values for the following fields: Data Source Name: The data source name. For example, MarvelTest. Service Host: The service host. For example, localhost. Service Port: The port at which the service is available. For example, Service Data Source: The service data source name active on the OpenAccess server. For example, MarvelTest. Custom Properties: The custom properties required to connect to the Marvel data source mainly the public key and the private key. Syntax:publickey=<public_key>; privatekey=<private_key> 5. Click Test Connect and then click OK. The Connection test was successful. message appears. If you receive an error, check whether the service is running and if you entered correct values for the fields mentioned above. 6. Click Apply and then click OK twice. 7. At the command prompt at location[openaccess-odbc-client]:\program Files\Progress\DataDirect\oaodbc72, execute the following command: odbcisql.exe For example, [OpenAccess-ODBC-CLIENT]:\Program Files\Progress\DataDirect\oaodbc72\odbcisql.exe. The ISQL> prompt appears. 8. At the ISQL> prompt, execute command connect MarvelIP. A connection is established with Marvel. 9. Execute an SQL query for obtaining data from the Marvel database. For example, SELECT * FROM comic WHERE ID=49015;. The query fetches a result from the Marvel database and the result is displayed on the ISQL> prompt. Connecting to Marvel Using the JDBC Client: 1. On your computer, go to [OAJDBCCLIENT-INSTALL-DIR]\testforjdbc. For example, C:\oajdbcclient\testforjdbc. 2. Double-click testforjdbc.bat. The Test for JDBC Tool window appears. 37

38 Chapter 5: Tutorial 3. Click Press Here To Continue. 4. From the Connection menu, click Connect to DB. The Select A Database window appears. 5. In the Database field enter the following string: jdbc:openaccess://localhost:19993;serverdatasource=marveltest; CustomProperties=(publickey=public_key;privatekey=private_key); then click Connect. The connection is established with Marvel and a new connection window opens up. 6. On the newly opened window, go to Connection > Load and Go. The Get Load And Go SQL window appears. 7. In Type SQL Here, you can execute metadata queries to obtain table and column information. For example, type the following query: SELECT TOP 100 * FROM Comic. The data is fetched from the Comic table and records are displayed on the connection window. 38

39 Customizing Marvel Driver Customizing Marvel Driver This section provides the details on the customization required for the Marvel data source. Please refer to the pre-built Marvel Interface Provider code installed at: RestGenerator\sample\Marvel\src. For creating the Marvel driver, we need to add the following customization: 1. Authentication Changes:These changes are implemented in the com\ddtek\marvel\connection package. For every request, Marvel needs the following query parameters to be set. a. ts (timestamp) b. apikey (publickey) c. hash (md5 signature). This will be created based on publickey and privatekey. For every request, hash is calculated and appended to the request URL. This implementation is available in RequestProcessor.java. The ConnectionHelper.java file, validates if the user has provided the publickey and privatekey as part of the connection URL under custom properties. If the keys are not provided, an exception is thrown. For performing authentication changes, check the following files available at com\ddtek\marvel\connection: RequestProcessor.java ConnectionHelper.java Utility.java 2. Data processor changes: These changes are implemented in the com\ddtek\marvel\dataprocessor package. A data processor file is generated in this package for every table defined in Schema. For example, for Comic and Creator tables defined in Schema the following files are generated. ComicDataProcessor.java CreatorDataProcessor.java A data processor allows users to define: The request URL that is to be invoked. The processing of JSON response data. For performing changes related to definition of the requests and responses, check the following files available at com\ddtek\marvel\dataprocessor: ComicDataProcessor.java CreatorDataProcessor.java JSONUtil.java 39

40 Chapter 5: Tutorial Tip:To perform customization for the Marvel driver, copy the pre-built Marvel IP code from the ip\restgenerator\sample\marvel\src folder location to the development location of MarvelTest (ip\restgenerator\marveltest\src). Listed below are the lists of files to be copied: 1. Copy the following files from com\ddtek\marvel\connection to com\ddtek\marveltest\connection. RequestProcessor.java ConnectionHelper.java Utility.java 2. Copy the following files from com\ddtek\marvel\dataprocessor to com\ddtek\marveltest\dataprocessor. ComicDataProcessor.java CreatorDataProcessor.java JSONUtil.java Edit all the copied files to update the package to com.ddtek.marveltest instead of com.ddtek.marvel. 40

41 Index Index C Configuring OpenAccess for REST Data Source 31 Connecting to Marvel Data Source 14 Connecting to sample data source 13 Connecting to Sample Rest Source 14 contacting Customer Support 9 conventions, typographical 8 Creating Service on OpenAccess Server 31 Customer Support, contacting 9 Customizing IP Code 30 Customizing the Marvel Test Driver 39 D Defining Data Source Properties 19 Defining Data Source Schema 20 XML Schema Format 20 Developing IP 19, 25, 30 Customizing IP Code 30 Defining Data Source Properties 19 Defining Data Source Schema 19 Generating IP Template Code 25 G Generating a Sample Driver 33 Generating a Marvel Test Driver 33 Generating IP Template Code 25 Generating the Marvel Test Driver 33 H help, online 9 I Installation 13 OpenAccess REST IP Generator 13 OpenAccess SDK 13 Installing OpenAccess SDK 13 O OpenAccess REST IP Generator Installation 13 T Tutorial 33 X XML Schema Format 21 Column Information 21 General Table Information 21 Index Information 21 Relationship Information 21 XML Table Column Information 21 XML Table General Information 21 XML Table Index Information 22 XML Table Information Column Information 21 General Table Information 21 Index Information 22 Relationship Information 23 XML Table Relationship Information 23 41

42 Index 42