The Progress DataDirect Autonomous REST Connector for JDBC

Transcription

1 The Progress DataDirect Autonomous REST Connector for JDBC Quick Start for Using HTTP Header Authentication Release

2

3 Copyright 2018 Progress Software Corporation and/or one of its subsidiaries or affiliates. 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. Corticon, DataDirect (and design), DataDirect Cloud, DataDirect Connect, DataDirect Connect64, DataDirect XML Converters, DataDirect XQuery, DataRPM, Deliver More Than Expected, Icenium, Kendo UI, Kinvey, NativeScript, OpenEdge, Powered by Progress, Progress, Progress Software Developers Network, Rollbase, SequeLink, Sitefinity (and Design), Sitefinity, SpeedScript, Stylus Studio, TeamPulse, Telerik, Telerik (and Design), Test 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. Analytics360, AppServer, BusinessEdge, DataDirect Autonomous REST Connector, DataDirect Spy, SupportLink, DevCraft, Fiddler, JustAssembly, JustDecompile, JustMock, NativeChat, NativeScript Sidekick, OpenAccess, ProDataSet, Progress Results, Progress Software, ProVision, PSE Pro, SmartBrowser, SmartComponent, SmartDataBrowser, SmartDataObjects, SmartDataView, SmartDialog, SmartFolder, SmartFrame, SmartObjects, SmartPanel, SmartQuery, SmartViewer, SmartWindow, and WebClient 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. Updated: 2018/11/28 3

4 Copyright 4

5 Quick Start: Accessing REST data sources using HTTP header authentication The Progress DataDirect Autonomous REST Connector for JDBC is a driver supports SQL read-only access to REST API data sources. This quick start guides provides the basic information necessary to install, configure, and connect to REST API data sources that authenticate by passing tokens using HTTP headers. To take full advantage of the features and functionality available for your driver, refer to the product documentation library at: Progress DataDirect Documentation Library Note: OEM CUSTOMERS: Refer to the Progress DataDirect for JDBC Drivers Distribution Guide for information on installing, branding, unlocking, and distributing your branded drivers. This quick start covers the following topics: Before you start on page 5 Requirements and support on page 6 Downloading the driver on page 6 Installing the JDBC driver on page 7 Setting the classpath on page 9 Driver and DataSource classes on page 9 Creating an input REST File on page 9 Using connection properties on page 15 Connecting to a DataSource on page 17 Troubleshooting setup/connection issues on page 29 Additional resources on page 30 Before you start Before you get started, you need the following: Appropriate user permissions to modify your environment and to read, write, and execute various files in the DataDirect for JDBC installation directory. Connection information: Authentication Method: The method your endpoints use authenticate users. The Autonomous REST Connector supports basic, token based (HTTP Header and URL based), and no authentication. HTTP Header Name: The name of your HTTP header used for authentication, if it differs from the default value of Authorization. 5

6 Chapter 1: Quick Start: Accessing REST data sources using HTTP header authentication Security Token: The security token required to make a connection to your REST API endpoint. (Optional) User Name:The user ID used to access your data source, if required by your endpoints. HTTP Endpoints: A list of the HTTP endpoints that you want to map to the relational view. Note that additional endpoints can be added during later sessions. (Optional) Location to store internal driver files: The path you want the driver to use to generate and store internal configuration files. This location is not used when the driver uses memory to store mapping information for the session (the default). When configured to generate internal configuration files (CreateMap=ForceNew NotExist), the driver will attempt to use the following directories by default: For Windows: application_data_folder\local\progress\datadirect\autorest_schema\ For UNIX/Linux: ~/progress/datadirect/autorest_schema/ For licensed installations, you will also need the following information that was provided by Progress DataDirect: Control Number (IPE Key) Serial Number Requirements and support Driver/Client Software Requirements: Java SE 8 or higher Supported Data Sources: The driver supports a variety of REST API deployments that employ: Payloads expressed in the JSON format. Basic, token (URL or header-based), or no authentication. Downloading the driver To download the Autonomous REST Connector for JDBC: 1. Visit the Progress DataDirect Connectors Download page. 2. Select Rest API from the list of data sources. 3. Select JDBC for the interface. 4. Select your OS when prompted for your OS and architecture. 5. Fill in the registration form with your contact information. 6. Review the End User License Agreement. If you agree, select the corresponding box; then, click Download. 6

7 Installing the JDBC driver The installer program has been downloaded. See "Installing the JDBC driver" for detailed instructions. See also Installing the JDBC driver on page 7 Installing the JDBC driver This section provides instructions for installing your downloaded files using the GUI installer. Note: OEM CUSTOMERS: Refer to the Progress DataDirect for JDBC Drivers Distribution Guide for information on installing, branding, unlocking, and distributing your branded drivers. Note: Make sure that the Java Virtual Machine (JVM) is defined on your path. Java SE 8 or higher is required to use the driver. 1. Unzip the files to a temporary directory, maintaining the directory structure of the zip file. 2. From the installer directory, run the appropriate installer file to start the installer. Windows: PROGRESS_DATADIRECT_JDBC_INSTALL.exe Non-Windows: PROGRESS_DATADIRECT_JDBC_INSTALL.jar Important: The Java installer can be run on most platforms, including Windows; however, if you run the Java installer on Windows, turn off User Account Controls or select a non-system directory as the installation directory. The Windows installer allows you to install the driver in the Program Files system directory on Windows without turning off User Account Controls. 3. The Introduction window appears. Click Next. 4. The License Agreement window appears. Make sure that you read and understand the license agreement. To continue with the installation, select the I accept the terms in the License Agreement option; then, click Next. 5. The Install Directory window appears. In the Where Would You Like to Install? field, type the path, including the drive letter, of the product installation directory or click the Choose button to browse to and select an installation directory. Verify the installation directory. Click Next to continue. 6. Choose the type of installation to perform. Select one of the following options. Evaluation installation (will expire in 15 days). Select this option to install evaluation versions of all available drivers. Click Next to continue with the installation. Skip to Step 10 on page 8. OEM or Licensed installation. Select this option if you have purchased a licensed version of one or multiple drivers. Click Next. If you are updating a currently installed driver, skip to Step 8 on page 8; otherwise, proceed to the next step. 7. Type the Control Number that was provided by Progress DataDirect in the Control # field, and click the Validate button. You can add multiple control numbers consecutively. A tree menu of drivers with valid licenses appears in the selection box. For example, the following image demonstrates an Apache Cassandra installation. 7

8 Chapter 1: Quick Start: Accessing REST data sources using HTTP header authentication 8. From the tree menu, select the drivers that you want to install. Click Next to continue. Drivers that are already installed will be listed under Drivers (Installed) and cannot be deselected. To remove installed drivers, you must uninstall the product. 9. Enter name, company, and serial number in the fields provided. Click Next to continue. a) Type your name and company name into the corresponding fields. b) Type the serial number that was provided by Progress DataDirect. 10. The Pre-Installation Summary window appears. Review the installation information. Click Previous to revise selections; or click Install to begin the installation. 11. When the installation finishes, the Install Complete window appears. Click Done to exit the installer program. 8

9 Setting the classpath Setting the classpath The driver must be defined on your CLASSPATH before you can connect. The CLASSPATH is the search string your Java Virtual Machine (JVM) uses to locate JDBC drivers on your computer. If the driver is not defined on your CLASSPATH, you will receive a class not found exception when trying to load the driver. Set your system CLASSPATH to include the autorest.jar file as shown, where install_dir is the path to your product installation directory. install_dir/lib/autorest.jar Windows Example CLASSPATH=.;C:\Program Files\Progress\DataDirect\JDBC_60\lib\autorest.jar UNIX Example CLASSPATH=.:/opt/Progress/DataDirect/JDBC_60/lib/autorest.jar Driver and DataSource classes The following are the Driver and DataSource classes used by the driver: Driver class: com.ddtek.jdbc.autorest.autorestdriver DataSource class: com.ddtek.jdbcx.autorest.autorestdatasource Creating an input REST File The driver supports an optional input REST file that allows you to specify multiple endpoints, define POST requests, and configure paging. You will need to create an input REST file if your session: Accesses multiple endpoints Issues POST requests Accesses endpoints that require paging If your session does not require a REST file, you can specify your endpoint, for GET requests, using the Sample connection property instead. For sessions that use a REST file, you will need to create a REST file and specify its location using the Config property. The input REST file is a simple text file that uses the file_name.rest naming convention. To configure the file, you will need to populate the contents with a list of comma-separated endpoints and requests using the formats described in this section. A sample REST file, named example.rest, is installed in the install_dir\restfiles directory. For additional examples, see "Sample Input REST File." 9

10 Chapter 1: Quick Start: Accessing REST data sources using HTTP header authentication The following example demonstrates the basic format used in the REST file when mapping a table to the schema: { "<table_name1>":"<endpoint1>", "<table_name2>":"<endpoint2>", "<table_name3>":"<endpoint3>" } Specifying Endpoints for GET Request with Unparameterized Paths To specify endpoints for unparameterized GET requests, use the following format: "<table_name>":"<host_name>/<endpoint_path>", table_name is the name of the relational table to which the driver maps the endpoint. For example, country. host_name (optional) is the protocol and host name components of the URL endpoint. For example, You can omit this value by specifying the host name using the ServerName property. endpoint_path is the path component of the URL endpoint. For example, countries. For example, the following demonstrates a GET request that will map to the countries table. "countries":" 10

11 Creating an input REST File Specifying Endpoints for GET Request with Parameterized Paths To specify parameterized GET requests, use the following format: "<table_name>":"<host_name>/<endpoint_path1>/{<param_name>:<param_value>}[/<endpoint_path2>]", table_name is the name of the relational table to which the driver maps the endpoint. For example, states. host_name (optional) is the protocol and host name components of the URL endpoint. For example, You can omit this value by specifying the host name using the ServerName property. endpoint_path is the path component of the URL endpoint. For example, states. param_name is the parameter identifier used for filtering the request. For example, countrycode. param_value is the parameter value used for filtering the request. For example, USA. For example, the following demonstrates a GET request that will map to the states table. "states":" 11

12 Chapter 1: Quick Start: Accessing REST data sources using HTTP header authentication Specifying Endpoints for GET Requests with Query Parameters Use the following format to specify endpoints for GET requests with argument parameters. Multiple argument parameters withing the same endpoint are separated by an ampersand (&). "<table_name>":"<host_name>/<endpoint_path>?<parameter>=<value>[&...]", table_name is the name of the relational table to which the driver maps the endpoint. For example, timeseries. host_name (optional) is the protocol and host name components of the URL endpoint. For example, You can omit this value by specifying the host name using the ServerName property. endpoint_path is the path component of the URL endpoint. For example, times. parameter value is the argument parameter component of the parameter=value pair used for filtering the request. For example, interval. is the value argument parameter used for filtering the request. For example, 5min. For example, the following demonstrates a GET request that will map to the timeseries table. "timeseries":" Defining a POST Request To use POST requests, you must define the request in the REST file in the JSON format. The definition entry is comprised of a path and body. The path contains the URL endpoint and the body used in requests, while the body defines documents and provides sample values. The driver then uses these sample values to define which data type to be used when executing a POST request. An entry for a POST request takes the following form: "table_name": { "#path": "<host_name>/<endpoint_path>", "#post": { "<field1>":"<value1>", "<field2>":"<value2>", } }, table_name is the name of the relational table to which the driver maps the endpoint. For example, countries2. 12

13 Creating an input REST File host_name (optional) is the protocol and host name components of the URL endpoint. For example, You can omit this value by specifying the host name using the ServerName property. endpoint_path is the path component of the URL endpoint. For example, country. document value is the document name of the document=value pair. For example, START_DATE. is the sample value the driver uses to determine the data type to use when executing a POST to that document. For example, For example, the following demonstrates an entry for a POST request that will map to the countries2 table. "countries2": { "#path": " "#post": { "start_date":" ", "end_date":" ", "departments":"[engineering,marketing,sales]", "tags":"[blue,green,red]" } }, Configuring Paging The driver supports two types of paging: offset and page numbering paging. To configure paging, specify values for the properties in the following tables that correspond to the type of paging you want to employ. Paging properties can be set for individual GET or POST requests by specifying these options in the body object. If paging properties are not specified, the driver will attempt to retrieve the first page for data sources that require paging. The following demonstrates configuring row offset paging for an unparametrized GET request: "table_name": { "#path": "<host_name>/<endpoint_path>", "#maximumpagesize":1000, "#firstrow":1, "#pagesizeparameter":"maxresults", "#rowoffsetparameter":"startat" }, table_name is the name of the relational table to which the driver maps the endpoint. For example, countries2. host_name (optional) is the protocol and host name components of the URL endpoint. For example, You can omit this value by specifying the host name using the ServerName property. 13

14 Chapter 1: Quick Start: Accessing REST data sources using HTTP header authentication endpoint_path is the path component of the URL endpoint. For example, country. Table 1: Row Offset Paging Properties Property #maximumpagesize #firstrow #pagesizeparameter #rowoffsetparameter The maximum page size in rows. Description The number of the first row. The default is 0; however, some systems begin numbering rows at 1. The name of the URI parameter that contains the page size. The name of the URI parameter that contains the starting row number for this set of rows. Table 2: Page Number Paging Properties Property #maximumpagesize #firstpage #pagesizeparameter #pagenumberparameter The maximum page size in rows. Description The number of the first page. The default is 0; however, some systems begin numbering pages at 1. The name of the URI parameter that contains the page size. When requesting a page of rows, this is the name of the URI parameter to contain the page number. 14

15 Using connection properties Sample input REST file The following is a sample input REST file that demonstrates GET requests, a POST requests, and a request configured for paging: { // a simple GET request without parameters to sample: "countries":" // A GET request with a parameter in the path: "states":" // A GET request with parameters as arguments "timeseries":" } }, }, } // A POST with parameters in the body "countries2": { "#path": " "#post": { "start_date":" ", "end_date":" ", "departments":"[engineering,marketing,sales]", "tags":"[blue,green,red]" // A GET with paging configured "products": { "#path": " "#maximumpagesize":1000, "#firstrow":1, "#pagesizeparameter":"maxresults", "#rowoffsetparameter":"startat" Using connection properties You can use connection properties to customize the driver for your environment. You can use these connection properties with either the JDBC Driver Manager or a JDBC data source. For a Driver Manager connection, a property is expressed as a key value pair and takes the form property=value. For a data source connection, a property is expressed as a JDBC method and takes the form setproperty(value). For a complete list of supported properties, refer to "Connection Property Descriptions" in the Progress DataDirect Autonomous REST Connector for JDBC User's Guide. The following tables summarize the essential connection properties used to configure the driver using HTTP header authentication. Note: All connection property names are case-insensitive. For example, AuthenticationMethod is the same as authenticationmethod. Required properties are noted as such. Note: The data type listed for each connection property is the Java data type used for the property value in a JDBC data source. 15

16 Chapter 1: Quick Start: Accessing REST data sources using HTTP header authentication Table 3: Essential Connection Properties for Sessions Using HTTP Header Authentication Property Characteristic Required Properties AuthenticationMethod Determines which authentication method the driver uses during the course of a session. If set to None, the driver does not attempt to authenticate. If set to Basic, the driver uses a hashed value, based on the concatenation of the user name and password, for authentication. In addition to the User and Password properties, you must also configure the AuthHeader property if the name of your HTTP header is not Authorization (the default). If set to HttpHeader, the driver passes security tokens via HTTP headers for authentication. You must also configure SecurityToken property and, if the name of your HTTP header is not Authorization (the default), the AuthHeader property. If set to UrlParameter, the driver passes security tokens via the URL for authentication. You must also configure the AuthParam and SecurityToken properties. The default is None. Config Specifies the name and location of the input REST file that contains the list of endpoints to sample and paging configuration information. For example, C:/path/to/mysite.rest. For more information on information on the REST file, see "Creating a REST File for Multiple End Points." Note: The Config property determines whether the driver uses an input REST file for the session. If no value is provided, an endpoint must be provided using the Sample property. Sample Specifies the endpoint to connect to and sample. Note: This option is required when not using an input REST file. SecurityToken Specifies the security token required to make a connection to your REST API endpoint. This option is required when token based authentication is enabled (AuthenticationMethod=HttpHeader UrlParameter); otherwise, this option is ignored. If a security token is required and you do not supply one, the driver returns an error indicating that an invalid user or password was supplied. Optional Properties AuthHeader Specifies the name of the HTTP header used for authentication. The default is Authorization. 16

17 Connecting to a DataSource Property CreateMap SchemaMap ServerName User Characteristic Determines whether the driver creates the internal files required for a relational map of the native data when establishing a connection. If set session, the driver uses memory to store the internal configuration information and relational map of native data. After the session, the view is discarded. If set to forcenew, the driver deletes the current internal configuration files and relational map specified by the SchemaMap property and creates a new set at the same location. If set to notexist, the driver uses the current internal files and relational map specified by the SchemaMap property. If the files do not exist, the driver creates them. Default: session Specifies the directory where internal files and the relational map of native data data are written. The driver looks for this location when connecting to an endpoint. If these files do not exist, the driver creates them. Windows default: application_data_folder\local\progress\datadirect\autorest_schema\ UNIX/Linux default: ~/progress/datadirect/autorest_schema/ Specifies the host name portion of the HTTP endpoint to which you send requests. Specify this value if you want to define endpoints without storing the host name component in the REST file. If required, specifies the user name used to access your endpoint. See also Connecting using the DriverManager on page 18 Connecting using data sources on page 23 Connecting to a DataSource Once the driver is installed and configured, you can connect from your application to your database in either of the following ways. Using the JDBC DriverManager, by specifying the connection URL in the DriverManager.getConnection() method. Creating a JDBC data source that can be accessed through the Java Naming Directory Interface (JNDI). 17

18 Chapter 1: Quick Start: Accessing REST data sources using HTTP header authentication Connecting using the DriverManager One way to connect to a Hive database is through the JDBC DriverManager using the DriverManager.getConnection() method. As the following example shows, this method specifies a string containing a connection URL. Connection conn = DriverManager.getConnection ("jdbc:datadirect:restful:authenticationmethod=httpheader; Config=C:/path/to/mysite.rest;SecurityToken=XaBARTsLZReM; User=jsmith;"); Passing the connection URL After setting the CLASSPATH, the required connection information needs to be passed in the form of a connection URL. The form of the connection URL differs depending on whether you are using a REST file For sessions using a REST file (sessions with multiple endpoints, PUSH requests, or paging): jdbc:datadirect:autorest://servername;authenticationmethod=httpheader; Config=rest_file_path;SecurityToken=token; User=user_name;[property=value[;...]]; For sessions using the Sample property: jdbc:datadirect:autorest:authenticationmethod=httpheader; Sample=sample_path;SecurityToken=token;User=user_name; [property=value[;...]]; where: servername optionally, specifies the host name portion of the HTTP endpoint to which you send requests. Specify this value if you want to define endpoints without the web server address in the REST config file. rest_file_path token specifies the name and location of the input REST file that contains a list of endpoints to sample, PUSH request definitions, and configuration information. See "Creating an Input REST file" for details. specifies the security token required to make a connection to your REST API endpoint. user_name specifies the user name used to access your endpoint, if required. property=value specifies connection property settings. Multiple properties are separated by a semi-colon. sample_path specifies the endpoint the sample when not using a REST file. The following examples demonstrate a URLs for sessions using HTTP header authentication: 18

19 Connecting to a DataSource For sessions using a REST file: Connection conn = DriverManager.getConnection ("jdbc:datadirect:autorest: AuthenticationMethod=HttpHeader;Config=C:/path/to/mysite.rest; SecurityToken=XaBARTsLZReM;User=jsmith;"); For sessions using the Sample property: Connection conn = DriverManager.getConnection ("jdbc:datadirect:autorest:authenticationmethod=httpheader; Sample= User=jsmith;"); See also Using connection properties on page 15 Testing a DriverManager Connection You can use DataDirect Test to establish and test a DriverManager connection. The screen shots in this section were taken on a Windows system. Important: Receiving a Connection Established notification from the DataDirect Test tool is only partial confirmation that the driver is properly configured. Since REST services lack traditional database structures, you will need to retrieve data from an endpoint using the following steps to confirm that you have successfully connected to your data. Take the following steps to establish a connection. 1. Navigate to the installation directory. The default location is: Windows systems: Program Files\Progress\DataDirect\JDBC_60\testforjdbc UNIX and Linux systems: /opt/progress/datadirect/jdbc_60/testforjdbc Note: For UNIX/Linux, if you do not have access to /opt, your home directory will be used in its place. 2. From the testforjdbc folder, run the platform-specific tool: testforjdbc.bat (on Windows systems) testforjdbc.sh (on UNIX and Linux systems) The Test for JDBC Tool window appears: 19

20 Chapter 1: Quick Start: Accessing REST data sources using HTTP header authentication 3. Click Press Here to Continue. The main dialog appears: 4. From the menu bar, select Connection > Connect to DB. The Select A Database dialog appears: 20

21 Connecting to a DataSource 5. Select the appropriate database template from the Defined Databases field. 6. In the Database field, specify the minimum connection properties required to test your connection: Using a REST file: Set the AuthenticationMethod, Config, and SecurityToken properties. Without a REST file: Set the AuthenticationMethod, Sample, and SecurityToken properties. For example: jdbc:datadirect:restful:authenticationmethod=httpheader; Sample= 7. If you are using user ID authentication, enter your user ID in the corresponding fields. 8. Click Connect. The JDBC/Database Output window reports that a connection has been established. Note: The Connection Established notification does not confirm that the Resftful driver is properly configured. You will need to retrieve data from an endpoint using the following steps to confirm that you have successfully connected to your data. 21

22 Chapter 1: Quick Start: Accessing REST data sources using HTTP header authentication 9. From the Connection window menu, select Connection / Create Statement. The Connection window indicates that the creation of the statement was successful. 10. Select Statement / Execute Stmt Query. DataDirect Test displays a dialog box that prompts for a SQL statement. 11. Type a Select statement and click Submit. Then, click Close. 12. Select Results / Show All Results. The data from your result set displays in the JDBC/Database Output scroll box. 22

23 Connecting to a DataSource If your data displays in the JDBC/Database Output box, you have successfully configured the driver. Connecting using data sources A JDBC data source is a Java object, specifically a DataSource object, that defines connection information required for a JDBC driver to connect to the database. Each JDBC driver vendor provides their own data source implementation for this purpose. A Progress DataDirect data source is Progress DataDirect s implementation of a DataSource object that provides the connection information needed for the driver to connect to a database. Because data sources work with the Java Naming Directory Interface (JNDI) naming service, data sources can be created and managed separately from the applications that use them. Because the connection information is defined outside of the application, the effort to reconfigure your infrastructure when a change is made is minimized. For example, if the database is moved to another database server, the administrator need only change the relevant properties of the DataSource object. The applications using the database do not need to change because they only refer to the name of the data source. How data sources are implemented Data sources are implemented through a data source class. A data source class implements the following interfaces. javax.sql.datasource javax.sql.connectionpooldatasource (allows applications to use connection pooling) The data source class for the Autonomous REST Connector is com.ddtek.jdbcx.autorest.autorestdatasource. Creating data sources The following example files provide details on creating and using Progress DataDirect data sources with the Java Naming Directory Interface (JNDI), where install_dir is the product installation directory. 23

24 Chapter 1: Quick Start: Accessing REST data sources using HTTP header authentication install_dir/examples/jndi/jndi_ldap_example.java can be used to create a JDBC data source and save it in your LDAP directory using the JNDI Provider for LDAP. install_dir/examples/jndi/jndi_filesystem_example.java can be used to create a JDBC data source and save it in your local file system using the File System JNDI Provider. See "Example data source" for an example data source definition for the example files. To connect using a JNDI data source, the driver needs to access a JNDI data store to persist the data source information. For a JNDI file system implementation, you must download the File System Service Provider from the Oracle Technology Network Java SE Support downloads page, unzip the files to an appropriate location, and add the fscontext.jar and providerutil.jar files to your CLASSPATH. These steps are not required for LDAP implementations because the LDAP Service Provider has been included with Java SE since Java 2 SDK, v1.3. Example data source To configure a data source using the example files, you will need to create a data source definition. The content required to create a data source definition is divided into three sections. First, you will need to import the data source class. For example: import com.ddtek.jdbcx.restful.restfuldatasource; Next, you will need to set the values and define the data source. For example, the following definition contains the minimum properties used for a data source using HTTP header authentication and a REST file: RestfulDataSource mds = new RestfulDataSource(); mds.setdescription("my Restful Data Source"); mds.setservername(" mds.setauthenticationmethod("httpheader"); mds.setconfig("c:/path/to/mysite.rest"); mds.setsecuritytoken("xabartslzrem"); The following example contains the minimum properties for a session using HTTP header authentication without a REST file. RestfulDataSource mds = new RestfulDataSource(); mds.setdescription("my Restful Data Source"); mds.setauthenticationmethod("httpheader"); mds.setsample(" mds.setsecuritytoken("xabartslzrem"); Finally, you will need to configure the example application to print out the data source attributes. Note that this code is specific to the driver and should only be used in the example application. For example, you would add the following section for a simple data source using HTTP header authentication with a REST file: if (ds instanceof RestfulDataSource) { RestfulDataSource jmds = (RestfulDataSource) ds; System.out.println("description=" + jmds.getdescription()); System.out.println("ServerName=" + jmds.getservername()); System.out.println("authenticationMethod=" + jmds.getauthenticationmethod()); System.out.println("Config=" + jmds.getconfig()); System.out.println("SecurityToken=" + jmds.getsecuritytoken()); System.out.println(); } 24

25 Connecting to a DataSource Calling a data source in an application Applications can call a Progress DataDirect data source using a logical name to retrieve the javax.sql.datasource object. This object loads the specified driver and can be used to establish a connection to the database. Once the data source has been registered with JNDI, it can be used by your JDBC application as shown in the following code example. Context ctx = new InitialContext(); DataSource ds = (DataSource)ctx.lookup("EmployeeDB"); Connection con = ds.getconnection("domino", "spark"); In this example, the JNDI environment is first initialized. Next, the initial naming context is used to find the logical name of the data source (EmployeeDB). The Context.lookup() method returns a reference to a Java object, which is narrowed to a javax.sql.datasource object. Then, the DataSource.getConnection() method is called to establish a connection. Testing a data source connection You can use DataDirect Test to establish and test a data source connection. The screen shots in this section were taken on a Windows system. Important: Receiving a Connection Established notification from the DataDirect Test tool is only partial confirmation that the driver is properly configured. Since REST services lack traditional database structures, you will need to retrieve data from an endpoint using the following steps to confirm that you have successfully connected to your data. Take the following steps to establish a connection. 1. Navigate to the installation directory. The default location is: Windows systems: Program Files\Progress\DataDirect\JDBC_60\testforjdbc UNIX and Linux systems: /opt/progress/datadirect/jdbc_60/testforjdbc Note: For UNIX/Linux, if you do not have access to /opt, your home directory will be used in its place. 2. From the testforjdbc folder, run the platform-specific tool: testforjdbc.bat (on Windows systems) testforjdbc.sh (on UNIX and Linux systems) The Test for JDBC Tool window appears: 25

26 Chapter 1: Quick Start: Accessing REST data sources using HTTP header authentication 3. Click Press Here to Continue. The main dialog appears: 4. From the menu bar, select Connection > Connect to DB via Data Source. The Select A Database dialog appears: 26

27 Connecting to a DataSource 5. Select a datasource template from the Defined Datasources field. 6. Provide the following information: a) In the Initial Context Factory, specify the location of the initial context provider for your application. b) In the Context Provider URL, specify the location of the context provider for your application. c) In the Datasource field, specify the name of your datasource. 7. If you are using user ID/password authentication, enter your user ID and password in the corresponding fields. 8. Click Connect. The JDBC/Database Output window reports that a connection has been established. Note: The Connection Established notification does not confirm that the Resftful driver is properly configured. You will need to retrieve data from an endpoint using the following steps to confirm that you have successfully connected to your data. 27

28 Chapter 1: Quick Start: Accessing REST data sources using HTTP header authentication 9. From the Connection window menu, select Connection / Create Statement. The Connection window indicates that the creation of the statement was successful. 10. Select Statement / Execute Stmt Query. DataDirect Test displays a dialog box that prompts for a SQL statement. 11. Type a Select statement and click Submit. Then, click Close. 12. Select Results / Show All Results. The data from your result set displays in the JDBC/Database Output scroll box. 28

29 Troubleshooting setup/connection issues If your data displays in the JDBC/Database Output box, you have successfully configured the driver. Troubleshooting setup/connection issues This section describes common setup/connection issues you may encounter while trying to establish a database connection with the driver as well as some potential reasons for these issues. If you are experiencing a problem not described in this section, comprehensive troubleshooting resources are available in the "Troubleshooting" section of the Progress DataDirect Autonomous REST Connector for JDBC User's Guide. Common setup/connection issues You are experiencing a setup/connection issue if you are encountering an error or hang while you are trying to make a database connection with the JDBC driver or are trying to configure the JDBC driver. Some common errors that are returned by the driver if you are experiencing a setup/connection issue include: class not found Specified driver could not be loaded. Data source name not found and no default driver specified. Unable to connect to destination. Invalid username/password; logon denied. Troubleshooting the issue Some common reasons that setup/connection issues occur are: 29

30 Chapter 1: Quick Start: Accessing REST data sources using HTTP header authentication The REST service is down. The driver jar file, autorest.jar, is not defined on your CLASSPATH. If the driver is not defined on your CLASSPATH, you will receive a class not found exception when trying to load the driver. See "Setting the classpath" for details. The JDBC driver s connection properties are not set correctly in the connection URL or data source. See "Configuring a data source" for more information. For example, the host name or port number are not correctly configured. Additional resources In addition to this quick start, the following resources enable you to take full advantage of the features and support offered for your driver. Product Documentation Library contains a comprehensive set of product documentation, including the following guides: Progress DataDirect for JDBC Drivers Installation Guide details requirements and procedures for installing the product. Progress DataDirect Autonomous REST Connector for JDBC User's Guide guides you through using and configuring the driver, provides detailed reference information, and explains the tools used to troubleshoot common problems. Progress Support Knowledgebase provides answers to questions, access to technical documentation, release notes, product alerts and other support information. Progress Community allows you to contribute, share, and network with other Progress users and employees. Technical Support provides technical support services, including maintenance services and opening a support case. Contacting technical support Progress DataDirect offers a variety of options to meet your 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 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 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. 30

31 Additional resources 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. 31

32 Chapter 1: Quick Start: Accessing REST data sources using HTTP header authentication 32