GridDB Advanced Edition JDBCドライバ説明書

Revision: 2163

Table of Contents

1 はじめに

1.1 本書の目的と構成

本書ではGridDB Advanced Edition JDBC ドライバの取り扱い方法および、注意事項について記載しています。GridDB Advanced Editionをご使用になる前に、必ずお読みください。なお、本書で説明する機能は、GridDB Advanced Editionライセンスを保有するユーザのみがご利用いただけます。

1.2 GridDB Advanced Editionとは

GridDB Advanced Edition では、GridDBのデータにSQLでアクセスできるインターフェースを提供します。本書では、GridDB Advanced Edition（以降、GridDB AEと記載します）のサポートするデータベースにアクセスするJavaのAPI(JDBC)の概要および仕様を説明します。

2 概要

JDBCパラメータのプログラムでの指定形式や使用できるデータ型、使用上の注意点を説明します。

2.1 接続方法

2.1.1 ドライバの指定

JDBCドライバファイル /usr/share/java/gridstore-jdbc.jar をクラスパスに追加します。これによりドライバが自動的に登録されます。さらに必要に応じて、以下のようにしてドライバクラスを読み込みます。通常は不要です。 

Class.forName("com.toshiba.mwcloud.gs.sql.Driver");

2.1.2 接続時のURL形式

URLは以下の形式となります。クラスタ構成方式がマルチキャスト方式の場合、通常は(A)の形式で接続してください。GridDBクラスタ側で自動的に負荷分散が行われ適切なノードに接続されます。GridDBクラスタとの間でマルチキャストでの通信ができない場合のみ、(B)の形式で接続してください。

(A)マルチキャスト方式のGridDBクラスタの適切なノードへ自動的に接続する場合 

jdbc:gs://(multicastAddress):(portNo)/(clusterName)/(databaseName)
  • multicastAddress：GridDBクラスタとの接続に使うマルチキャストアドレス。(デフォルト: 239.0.0.1)
  • portNo：GridDBクラスタとの接続に使うポート番号。(デフォルト: 41999)
  • clusterName：GridDBクラスタのクラスタ名
  • databaseName：データベース名。省略した場合はデフォルトデータベース(public)に接続します。

(B)マルチキャスト方式のGridDBクラスタ内のノードに直接接続する場合 

jdbc:gs://(nodeAddress):(portNo)/(clusterName)/(databaseName)
  • nodeAddress：ノードのアドレス
  • portNo：ノードとの接続に使うポート番号。(デフォルト: 20001)
  • clusterName：ノードが属するGridDBクラスタのクラスタ名
  • databaseName：データベース名。省略した場合はデフォルトデータベース(public)に接続します。

(C)固定リスト方式のGridDBクラスタに接続する場合

クラスタ構成方式が固定リスト方式の場合、この形式で接続してください。 

jdbc:gs:///(clusterName)/(databaseName)?notificationMember=(notificationMember)
  • clusterName：GridDBクラスタのクラスタ名
  • databaseName：データベース名。省略した場合はデフォルトデータベース(public)に接続します。
  • notificationMember：ノードのアドレスリスト(要URLエンコード)。デフォルトポートは20001
    • 例：192.168.0.10:20001,192.168.0.11:20001,192.168.0.12:20001

※notificationMemberはgs_cluster.jsonファイルを編集することで変更可能です。アドレスリストで使うポートは、gs_node.jsonファイルを編集することで変更可能です。

(D)プロバイダ方式のGridDBクラスタに接続する場合

クラスタ構成方式がプロバイダ方式の場合、この形式で接続してください。 

jdbc:gs:///(clusterName)/(databaseName)?notificationProvider=(notificationProvider)
  • clusterName：GridDBクラスタのクラスタ名
  • databaseName：データベース名。省略した場合はデフォルトデータベースに接続します
  • notificationProvider：アドレスプロバイダのURL(要URLエンコード)

※notificationProviderはgs_cluster.jsonファイルを編集することで変更可能です。

なお、(A)～(D)いずれの場合でも、ユーザ名・パスワードをURLに含める場合は、URLの末尾に次のように追加してください。 

?user=(ユーザ名)&password=(パスワード)

2.1.3 接続タイムアウトの設定

次のどちらかの方法で接続タイムアウトを設定できます。両方が設定された場合、(B)の設定が優先されます。どちらも設定されない場合、デフォルト値300秒(5分)が使用されます。

(A)DriverManager#setLoginTimeout(int seconds)で指定する

secondsの値によって、以下のように設定されます。設定後、DriverManager#getConnectionまたはDriver#connectで取得する全てのGridDB AEへのConnectionに接続タイムアウトが設定されます。

  • 値が1～Integer.MAX_VALUEの場合
    • 指定した秒数で設定されます
  • 値がInteger.MIN_VALUE～0の場合
    • 設定されません

(B)DriverManager#getConnection(String url, Properties info)またはDriver#connect(String url, Properties info)で指定する

引数infoにキー”loginTimeout”でプロパティを追加してください。キー”loginTimeout”に対応する値が数値に変換できた場合、取得したConnectionにのみ以下のように接続タイムアウトが設定されます。

  • 変換した値が1～Integer.MAX_VALUEの場合
    • 指定した秒数で設定されます
  • 変換した値が0以下 または Integer.MAX_VALUEより大きい場合
    • 設定されません

2.2 注意点

  • GridDB SE(Standard Edition)クライアントで作成したコンテナは、テーブルとみなしてGridDB AE JDBCドライバで参照、更新可能です。更新には行の更新だけでなく、コンテナのスキーマや索引の変更を含みます。また、GridDB AE JDBCドライバで作成したテーブルは、コンテナとしてGridDB SEクライアントで参照、更新可能です。
  • GridDB SEクライアントで作成した時系列コンテナをGridDB AE JDBCドライバからSQLで検索した場合、GridDB SEクライアントからTQLで検索した場合と異なり、主キーに対するORDER BY句がなければ結果は時刻順とはなりません。SQL結果の時刻順整列が必要な場合には主キーに対するORDER BYを指定してください。
  • 検索時の一貫性について、GridDB SEクライアントから検索した場合GridDB AE JDBCドライバからSQLで検索した場合とで見え方が異なることがあります。GridDBではトランザクションの隔離レベルとしてREAD COMMITTED をサポートしているため、検索では検索開始時点でコミット済みのデータを読み取ります。GridDB SEクライアントから検索した場合は、1検索要求を1回の読み取りで処理するためREAD COMMITTEDの通り検索開始時点でコミット済みデータのみを検索します。一方、GridDB AE JDBCドライバからSQLで検索した場合、要求されたSQLを複数回の読み取りで処理することがあり、このときそれぞれの読み取りがREAD COMMITTEDとなります。そのため、読み取りと読み取りの間で他クライアントのトランザクションがコミットされると、次の読み取りでその更新内容を読み取ってしまい、SQL全体としてはREAD COMMITTEDとならないことがあります。
  • SQLのヒット件数が多いと、「Memory limit exceeded」というエラーが発生することがあります。その場合は、以下のようにgs_node.jsonファイルにパラメータ /transaction/totalMemoryLimit および /dataStore/resultSetMemoryLimit の記述を追加し、SQL処理で使用するメモリの上限値を拡張してください。ただし、これらのパラメータは将来のバージョンで名前の変更や削除が行われる可能性があります。 
    // 例)上限値を指定する場合
// 記述がない場合のデフォルト値はそれぞれ1024MB、10240MBです。

"transaction":{
    "totalMemoryLimit":"2048MB"
}
"dataStore":{
    "resultSetMemoryLimit":"20480MB"
}

3 仕様

本章では、GridDB AE JDBCドライバの仕様について示します。主に、ドライバのサポート範囲ならびにJDBC標準との相違点について説明します。特記事項がなくJDBC標準に準拠しているAPIの仕様については、JDKのAPIリファレンスを参照してください。将来のバージョンでは、特に次の点が変更される可能性があります。

  • JDBC標準に準拠していない挙動
  • 未サポートの機能のサポート状況
  • エラーメッセージ

3.1 共通事項

3.1.1 サポートされるJDBCバージョン

JDBC4.1の一部機能に対応し、次の機能はサポートされません。

  • トランザクション制御
  • ストアドプロシージャ
  • バッチ実行

3.1.2 エラー処理

3.1.2.1 未サポート機能の使用
  • 標準機能
    • JDBC仕様に準拠したドライバがサポートすべき標準機能のうち、本ドライバにおいて現状サポートされていない機能を使用した場合、SQLFeatureNotSupportedExceptionが発生します。この挙動は、本来のSQLFeatureNotSupportedExceptionの仕様とは異なります。エラー名(後述)はJDBC_NOT_SUPPORTEDとなります。
  • オプション機能
    • JDBC仕様においてオプション機能に位置付けられており、SQLFeatureNotSupportedExceptionが発生する可能性のある機能のうち、本ドライバにおいてサポートされていない機能を使用した場合、JDBC仕様通りSQLFeatureNotSupportedExceptionが発生します。エラー名はJDBC_OPTIONAL_FEATURE_NOT_SUPPORTEDとなります。
3.1.2.2 クローズ済みのオブジェクトに対するメソッド呼び出し

JDBC仕様の通り、Connectionオブジェクトなどclose()メソッドを持つオブジェクトに対し、isClosed()以外のメソッドを呼び出すと、SQLExceptionが発生します。 エラー名はJDBC_ALREADY_CLOSEDとなります。

3.1.2.3 不正なnull引数

APIのメソッド引数として、nullが許容されないにも関わらず指定された場合、JDBC_EMPTY_PARAMETERエラーからなるSQLExceptionが発生します。JDBC仕様または本書で明示的にnullの受け入れを明記している引数以外は、nullを許容しません。

3.1.2.4 複数のエラー原因がある場合

複数のエラー原因がある場合は、いずれかのエラーを検知した時点でアプリケーションに制御が戻ります。特に、未サポート機能を使用しようとした場合のエラーは、他のエラーよりも先に検知します。たとえば、クローズ済みのConnectionオブジェクトに対してストアドプロシージャを作成しようとした場合は、クローズされていることではなく、未サポートであることを示すエラーが返ります。

3.1.2.5 例外の内容

ドライバよりスローされるチェック例外は、SQLExceptionもしくはSQLExceptionのサブクラスのインスタンスからなります。例外の詳細を取得するには、次のメソッドを使用します。

  • getErrorCode()
    • サーバ・クライアントのいずれかでGridDBが検知したエラーについて、エラー番号を返却します。具体的な番号やその原因については、エラーコード一覧を参照してください。
  • getSQLState()
    • 常にnullが設定されます。
  • getMessage()
    • エラー番号とエラーの説明を組にした、エラーメッセージを返却します。書式は次のようになります。 
      [Code:(エラー番号)] (エラーの説明)

      エラー一覧と対応しない番号のエラーが発生した場合、エラーメッセージは次のようになります。 

      (エラーの詳細)
3.1.2.6 エラー一覧

ドライバ内部で検出される主なエラーの一覧は次の通りです。

エラー番号エラーコード名エラー説明の書式
(別記)JDBC_NOT_SUPPORTEDCurrently not supported
(別記)JDBC_OPTIONAL_FEATURE_NOT_SUPPORTEDOptional feature not supported
(別記)JDBC_EMPTY_PARAMETERThe parameter (引数名) must not be null
(別記)JDBC_ALREADY_CLOSEDAlready closed
(別記)JDBC_COLUMN_INDEX_OUT_OF_RANGEColumn index out of range
(別記)JDBC_VALUE_TYPE_CONVERSION_FAILEDFailed to convert value type
(別記)JDBC_UNWRAPPING_NOT_SUPPORTEDUnwrapping interface not supported
(別記)JDBC_ILLEGAL_PARAMETERIllegal value: (引数名)
(別記)JDBC_UNSUPPORTED_PARAMETER_VALUEUnsupported (パラメータ名)
(別記)JDBC_ILLEGAL_STATEProtocol error occurred
(別記)JDBC_INVALID_CURSOR_POSITIONInvalid cursor position
(別記)JDBC_STATEMENT_CATEGORY_UNMATCHEDWritable query specified for read only request Read only query specified for writable request
(別記)JDBC_MESSAGE_CORRUPTEDProtocol error

エラーの発生源となる元のエラーがある場合などは、上記のエラー説明の末尾に追加の詳細メッセージが追加されることがあります。この他のエラーはエラーコード表を参照してください。

3.2 API仕様詳細

3.2.1 Connectionインターフェース

Connectionインターフェースの各メソッドについて説明します。 特に説明のない限り、Connectionがクローズされていない場合の説明のみを記載します。

3.2.1.1 トランザクション制御

トランザクション制御はサポートしません。ただし、トランザクションを使用するアプリケーションにおいても疑似的に動作するよう、機能制限を原因とするエラーを引き起こしません。

  • getAutoCommit()
    • 常にtrueを返します。JDBC仕様とは異なります。
  • setAutoCommit(autoCommit)
    • パラメータを無視します。JDBC仕様とは異なります。
  • commit()/rollback()
    • 要求を無視します。JDBC仕様とは異なります。
  • setTransactionIsolation(level)
    • TRANSACTION_READ_COMMITTEDのみサポートしているかのように振る舞います。DatabaseMetaData#supportsTransactionIsolationLevel(level)と対応します。
3.2.1.2 各種属性の設定・変更
  • isReadOnly()
    • 常にfalseを返します。JDBC仕様とは異なります。
  • setReadOnly(readOnly)
    • パラメータを無視します。JDBC仕様とは異なります。
  • setHoldability(holdability)
    • CLOSE_CURSORS_AT_COMMITのみサポートします。
  • createStatement(resultSetType, resultSetConcurrency)
    • resultSetTypeはTYPE_FORWARD_ONLYのみ、resultSetConcurrencyはCONCUR_READ_ONLYのみサポートします。
  • createStatement(resultSetType, resultSetConcurrency, resultSetHoldability)
    • resultSetTypeはTYPE_FORWARD_ONLYのみ、resultSetConcurrencyはCONCUR_READ_ONLYのみ、resultSetHoldabilityはCLOSE_CURSORS_AT_COMMITのみサポートします。
  • prepareStatement(sql, resultSetType, resultSetConcurrency)
    • resultSetTypeはTYPE_FORWARD_ONLYのみ、resultSetConcurrencyはCONCUR_READ_ONLYのみサポートします。
  • prepareStatement(sql, resultSetType, resultSetConcurrency, resultSetHoldability)
    • resultSetTypeはTYPE_FORWARD_ONLYのみ、resultSetConcurrencyはCONCUR_READ_ONLYのみ、resultSetHoldabilityはCLOSE_CURSORS_AT_COMMITのみサポートします。
3.2.1.3 未サポートの機能
  • 標準機能
    • prepareCall(sql)
  • オプション機能
    • abort(executor)
    • createArrayOf(typeName, elements)
    • createBlob()
    • createClob()
    • createNClob()
    • createSQLXML()
    • createStruct(typeName, attributes)
    • getNetworkTimeout()
    • getSchema()
    • getTypeMap()
    • prepareCall(sql, resultSetType, resultSetConcurrency)
    • prepareCall(sql, resultSetType, resultSetConcurrency, resultSetHoldability)
    • prepareStatement(sql, autoGeneratedKeys)
    • prepareStatement(sql, columnIndexes)
    • prepareStatement(sql, columnNames)
    • releaseSavepoint(savepoint)
    • rollback(savepoint)
    • setNetworkTimeout(executor, milliseconds)
    • setSavepoint()

3.2.2 DatabaseMetaDataインターフェース

3.2.2.1 ResultSetを返す属性
  • getColumns(catalog, schemaPattern, tableNamePattern, columnNamePattern)
    • 指定のtableNamePatternに対応するResultSetを返却します。tableNamePatternにはワイルドカードは指定できず、完全一致するテーブルがなければ空の結果を返却します。指定された他の絞り込み条件は無視されます。
      結果カラム名値
      TABLE_CATnull
      TABLE_SCHEMnull
      TABLE_NAME(テーブル名)
      COLUMN_NAME(カラム名)
      DATA_TYPE(DatabaseMetaData#getTypeInfo()参照)
      TYPE_NAME(ResultSetMetaData#getColumnTypeName()の結果の値と対応)
      COLUMN_SIZE2000000000
      BUFFER_LENGTH2000000000
      DECIMAL_DIGITS10
      NUM_PREC_RADIX10
      NULLABLEPRIMARY KEYまたはNOT NULL制約があるカラムは 0 (DatabaseMetaData#columnNoNulls)
      それ以外は 1 (DatabaseMetaData#columnNullable)
      REMARKSnull
      COLUMN_DEFnull
      SQL_DATA_TYPE0
      SQL_DATETIME_SUB0
      CHAR_OCTET_LENGTH2000000000
      ORDINAL_POSITION(1から開始)
      IS_NULLABLEPRIMARY KEYまたはNOT NULL制約があるカラムは'NO'
      それ以外は'YES'
      SCOPE_CATLOGnull
      SCOPE_SCHEMAnull
      SCOPE_TABLEnull
      SOURCE_DATA_TYPEnull
      IS_AUTOINCREMENT'NO'
      IS_GENERATEDCOLUMN'NO'
  • getIndexInfo(catalog, schema, table, unique, approximate)
    • 指定のtableに対応するResultSetを返却します。tableは既存のテーブル名と一致する必要があります。uniqueがfalse以外の場合、結果は空になります。指定された他の絞り込み条件・パラメータは無視されます。なおCREATE INDEX文で作成された索引以外は結果に含まれません。
      結果カラム名値
      TABLE_CATnull
      TABLE_SCHEMnull
      TABLE_NAME(テーブル名)
      NON_UNIQUEtrue
      INDEX_QUALIFIERnull
      INDEX_NAME(索引名)
      TYPEtableIndexHashed(2) または tableIndexOther(3)
      ORDINAL_POSITION(1から開始)
      COLUMN_NAME(カラム名)
      ASC_OR_DESCnull
      CARDINALITY0
      PAGES0
      FILTER_CONDITIONnull
  • getPrimaryKeys(catalog, schema, table)
    • 主キーの有無に応じて、TABLE_NAME、COLUMN_NAME、KEY_SEQが設定されたResultSetを返却します。返却されるResultSetの他のカラムには全てnullが設定されます。指定された他の絞り込み条件は無視されます。なおtableにnullを指定した場合は、tableについて絞り込み条件無しとみなします。
  • getTables(catalog, schemaPattern, tableNamePattern, types)
    • TABLE_NAMEとTABLE_TYPEのみ設定されたResultSetを返却します。TABLE_TYPEには常に'TABLE'が設定されます。typesが指定された場合は、typesに'TABLE'と一致する要素が存在しなければ常に空の結果を返します。types内の文字列要素の大文字小文字表記の違いは無視されます。tableNamePatternによる絞り込みは有効です。catalog、schemaPatternの絞り込み条件は全て無視します。なおtableNamePatternにnullを指定した場合は、tableNamePatternによる絞り込み条件無しとみなします。
  • getTableTypes()
    • TABLE_TYPEとして'TABLE'が設定された、1つの行からなるResultSetを返却します。
  • getTypeInfo()
    • JDBC仕様通りに振る舞います。すべての型で共通の情報、型別の情報は以下の通りです。
      結果カラム名値
      PRECISION0
      LITERAL_PREFIXnull
      LITERAL_SUFFIXnull
      CREATE_PARAMSnull
      NULLABLE1 (DatabaseMetaData#typeNullable)
      CASE_SENSITIVE1
      SEARCHABLE3 (DatabaseMetaData#typeSearchable)
      UNSIGNED_ATTRIBUTE0
      FIXED_PREC_SCALE0
      AUTO_INCREMENT0
      LOCAL_TYPE_NAMEnull
      MINIMUM_SCALE0
      MAXIMUM_SCALE0
      SQL_DATA_TYPE0
      SQL_DATETIME_SUB0
      NUM_PREC_RADIX10
      TYPE_NAMEDATA_TYPE
      'BOOL'-7 (Types#BIT)
      'BYTE'-6 (Types#TINYINT)
      'SHORT'5 (Types#SMALLINT)
      'INTEGER'4 (Types#INTEGER)
      'LONG'-5 (Types#BIGINT)
      'FLOAT'6 (Types#FLOAT)
      'DOUBLE'8 (Types#DOUBLE)
      'TIMESTAMP'93 (Types#TIMESTAMP)
      'STRING'12 (Types#VARCHAR)
      'BLOB'2004 (Types#BLOB)
      'UNKNOWN'1111 (Types#OTHER)
3.2.2.2 単純値を返す属性
メソッド結果
allProceduresAreCallable()false
allTablesAreSelectable()true
autoCommitFailureClosesAllResultSets()false
dataDefinitionCausesTransactionCommit()false
dataDefinitionIgnoredInTransactions()true
deletesAreDetected(type)false
doesMaxRowSizeIncludeBlobs()false
generatedKeyAlwaysReturned()false
getCatalogSeparator()"."
getCatalogTerm()"catalog"
getDefaultTransactionIsolation()TRANSACTION_READ_COMMITTED
getExtraNameCharacters(). - / = (順不同)
getIdentifierQuoteString()"
getMaxBinaryLiteralLength()0
getMaxCatalogNameLength()0
getMaxCharLiteralLength()0
getMaxColumnNameLength()0
getMaxColumnsInGroupBy()0
getMaxColumnsInIndex()0
getMaxColumnsInOrderBy()0
getMaxColumnsInSelect()0
getMaxColumnsInTable()0
getMaxConnections()0
getMaxCursorNameLength()0
getMaxIndexLength()0
getMaxSchemaNameLength()0
getMaxProcedureNameLength()0
getMaxRowSize()0
getMaxStatementLength()0
getMaxStatements()0
getMaxTableNameLength()0
getMaxTablesInSelect()0
getMaxUserNameLength()0
getProcedureTerm()"procedure"
getResultSetHoldability()CLOSE_CURSORS_AT_COMMIT
getRowIdLifetime()true
getSchemaTerm()"schema"
getSearchStringEscape()"\"
getSQLKeywords()""
getSQLStateType()sqlStateSQL99
getStringFunctions()""
getSystemFunctions()""
getURL()null
getUserName()(ユーザ名)
insertsAreDetected(type)false
isCatalogAtStart()true
isReadOnly()false
locatorsUpdateCopy()false
nullPlusNonNullIsNull()true
nullsAreSortedAtEnd()false
nullsAreSortedAtStart()false
nullsAreSortedHigh()true
nullsAreSortedLow()false
othersDeletesAreVisible(type)false
othersInsertsAreVisible(type)false
othersUpdatesAreVisible(type)false
ownDeletesAreVisible(type)false
ownInsertsAreVisible(type)false
ownUpdatesAreVisible(type)false
storesLowerCaseIdentifiers()false
storesLowerCaseQuotedIdentifiers()false
storesMixedCaseIdentifiers()true
storesMixedCaseQuotedIdentifiers()false
storesUpperCaseIdentifiers()false
storesUpperCaseQuotedIdentifiers()false
supportsAlterTableWithAddColumn()false
supportsAlterTableWithDropColumn()false
supportsANSI92EntryLevelSQL()false
supportsANSI92FullSQL()false
supportsANSI92IntermediateSQL()false
supportsBatchUpdates()false
supportsCatalogsInDataManipulation()false
supportsCatalogsInIndexDefinitions()false
supportsCatalogsInPrivilegeDefinitions()false
supportsCatalogsInProcedureCalls()false
supportsCatalogsInTableDefinitions()false
supportsColumnAliasing()true
supportsConvert()false
supportsConvert(fromType, toType)false
supportsCoreSQLGrammar()true
supportsCorrelatedSubqueries()true
supportsDataDefinitionAndDataManipulationTransactions()false
supportsDataManipulationTransactionsOnly()false
supportsDifferentTableCorrelationNames()false
supportsExpressionsInOrderBy()true
supportsExtendedSQLGrammar()false
supportsFullOuterJoins()false
supportsGetGeneratedKeys()false
supportsGroupBy()true
supportsGroupByBeyondSelect()true
supportsGroupByUnrelated()true
supportsIntegrityEnhancementFacility()false
supportsLikeEscapeClause()true
supportsLimitedOuterJoins()true
supportsMinimumSQLGrammar()true
supportsMixedCaseIdentifiers()false
supportsMixedCaseQuotedIdentifiers()true
supportsMultipleOpenResults()false
supportsMultipleResultSets()false
supportsMultipleTransactions()false
supportsNamedParameters()false
supportsNonNullableColumns()true
supportsOpenCursorsAcrossCommit()false
supportsOpenCursorsAcrossRollback()false
supportsOpenStatementsAcrossCommit()false
supportsOpenStatementsAcrossRollback()false
supportsOrderByUnrelated()true
supportsOuterJoins()true
supportsPositionedDelete()false
supportsPositionedUpdate()false
supportsResultSetConcurrency(type, concurrency)typeがTYPE_FORWARD_ONLY、concurrencyがCONCUR_READ_ONLYの場合のみ
supportsResultSetHoldability(holdability)CLOSE_CURSORS_AT_COMMITの場合のみ
supportsResultSetType()TYPE_FORWARD_ONLYの場合のみ
supportsSavepoints()false
supportsSchemasInDataManipulation()false
supportsSchemasInIndexDefinitions()false
supportsSchemasInPrivilegeDefinitions()false
supportsSchemasInProcedureCalls()false
supportsSchemasInTableDefinitions()false
supportsSelectForUpdate()false
supportsStatementPooling()false
supportsStoredFunctionsUsingCallSyntax()false
supportsStoredProcedures()false
supportsSubqueriesInComparisons()false
supportsSubqueriesInExists()true
supportsSubqueriesInIns()true
supportsSubqueriesInQuantifieds()false
supportsTableCorrelationNames()false
supportsTransactionIsolationLevel(level)TRANSACTION_READ_COMMITTEDの場合のみ
supportsTransactions()true
supportsUnion()true
supportsUnionAll()true
updatesAreDetected(type)false
usesLocalFilePerTable()false
usesLocalFiles()false
3.2.2.3 未サポートの属性
メソッド結果
getAttributes空のResultSet
getBestRowIdentifier空のResultSet
getCatalogs空のResultSet
getClientInfoProperties空のResultSet
getColumnPrivileges空のResultSet
getCrossReference空のResultSet
getExportedKeys空のResultSet
getFunctionColumns空のResultSet
getFunctions空のResultSet
getImportedKeys空のResultSet
getProcedureColumns空のResultSet
getProcedures空のResultSet
getPseudoColumns空のResultSet
getSchemas()空のResultSet
getSchemas(catalog, schemaPattern)空のResultSet
getSuperTables空のResultSet
getSuperTypes空のResultSet
getTablePrivileges空のResultSet
getUDTs空のResultSet
getVersionColumns空のResultSet

3.2.3 Statementインターフェース

3.2.3.1 フェッチサイズの設定・取得

値のチェックでは、このStatementのgetMaxRows()で得られるロウ数より超えないこともチェックします。この値に関する制限は、JDBC4.0より前のJDBC仕様でのみ明記されていました。ただし、以前のJDBC仕様とは異なり、getMaxRows()の結果がデフォルト値0に設定されている場合を除きます。

3.2.3.2 フェッチ方向の設定・取得

フェッチ方向はFETCH_FORWARDのみをサポートします。FETCH_FORWARD以外が指定された場合、SQLExceptionが発生します。

3.2.3.3 未サポートの機能
  • バッチ処理
    • バッチ処理はサポートしません。以下の機能を使用しようとすると、未サポートの標準機能を使用した場合と同一のエラーが発生します。
      • addBatch(sql)
      • clearBatch()
      • executeBatch()
  • 標準機能
    • 以下のメソッドの呼び出しは無視されます。JDBC仕様とは異なります。
      • setEscapeProcessing(enable)
  • オプション機能
    • 以下のメソッドを呼び出すとSQLFeatureNotSupportedExceptionが発生します。
      • closeOnCompletion()
      • execute(sql, autoGeneratedKeys)
      • execute(sql, columnIndexes)
      • execute(sql, columnNames)
      • executeUpdate(sql, autoGeneratedKeys)
      • executeUpdate(sql, columnIndexes)
      • executeUpdate(sql, columnNames)
      • getGeneratedKeys()
      • getMoreResults(current)
      • isCloseOnCompletion()

3.2.4 PreparedStatementインターフェース

3.2.4.1 パラメータの設定・取得

以下のメソッドをサポートします。設定されていないパラメータがある状態でexecuteQueryなどクエリ実行APIを呼び出すと、SQLExceptionが発生します。

  • clearParameters()
  • getMetaDeta()
  • getParameterMetaData()
  • setBlob(int parameterIndex, Blob x)
  • setBoolean(int parameterIndex, boolean x)
  • setByte(int parameterIndex, byte x)
  • setDate(int parameterIndex, Date x)
  • setDouble(int parameterIndex, double x)
  • setFloat(int parameterIndex, float x)
  • setInt(int parameterIndex, int x)
  • setLong(int parameterIndex, long x)
  • setObject(int parameterIndex, Object x)
    • TIMESTAMP型のパラメータに設定する値としては、java.util.Dateのサブクラスのオブジェクトを受け入れます。
  • setShort(int parameterIndex, short x)
  • setString(int parameterIndex, String x)
  • setTime(int parameterIndex, Time x)
  • setTimestamp(int parameterIndex, Timestamp x)
3.2.4.2 SQLの実行

以下のメソッドをサポートします。

  • execute()
  • executeQuery()
  • executeUpdate()
3.2.4.3 未サポートの機能
  • 標準機能
    • 以下のメソッドを呼び出すとSQLFeatureNotSupportedExceptionが発生します。この挙動はJDBC仕様とは異なります。
      • addBatch()
      • setBigDecimal(int parameterIndex, BigDecimal x)
      • setDate(int parameterIndex, Date x, Calendar cal)
      • setTime(int parameterIndex, Time x, Calendar cal)
      • setTimestamp(int parameterIndex, Timestamp x, Calendar cal)
  • オプション機能
    • 以下のメソッドを呼び出すとSQLFeatureNotSupportedExceptionが発生します。引数を省略しているものは、全てのオーバーロードが未サポートです。
      • setArray
      • setAsciiStream
      • setBinaryStream
      • setBlob(int parameterIndex, InputStream inputStream)
      • setBlob(int parameterIndex, InputStream inputStream, long length)
      • setBytes
      • setCharacterStream
      • setClob
      • setNCharacterStream
      • setNClob
      • setNString
      • setNull
      • setObject(int parameterIndex, Object x, int targetSqlType)
      • setObject(int parameterIndex, Object x, int targetSqlType, int scaleOrLength)
      • setRef
      • setRowId
      • setSQLXML
      • setUnicodeStream
      • setURL

3.2.5 ParameterMetaDataインターフェース

全てのメソッドをサポートしますが、以下のメソッドは引数paramの値によらず常に固定の値を返します。

メソッド結果
getParameterTypeTypes.OTHER
getParamterTypeName"UNKNOWN"
getPrecision0
getScale0
isSignedfalse

3.2.6 ResultSetインターフェース

3.2.6.1 フェッチサイズの設定・取得

指定された値のチェックのみ行い、設定の変更は実際のフェッチ処理には影響しません。値のチェックでは、対象のResultSetの生成元のStatementのgetMaxRows()で得られるロウ数より超えないこともチェックします。この制限は、JDBC4.0より前のJDBC仕様でのみ明記されていました。ただし、以前のJDBC仕様とは異なり、getMaxRows()の結果がデフォルト値0に設定されている場合を除きます。実際のフェッチ処理には影響しませんが、変更した設定値を取得できます。

3.2.6.2 フェッチ方向の設定・取得

フェッチ方向はFETCH_FORWARDのみをサポートします。FETCH_FORWARD以外が指定された場合、SQLExceptionが発生します。この挙動はJDBC仕様とは異なります。

3.2.6.3 カーソル情報の取得

カーソルに関する以下のメソッドをサポートします。

  • isAfterLast()
  • isBeforeFirst()
  • isFirst()
  • isLast()
  • next()

フェッチ方向はFETCH_FORWARDのみをサポートしているため、次のメソッドを呼び出すとFETCH_FORWARDタイプのResultSetに対する呼び出しを原因とするSQLExceptionが発生します。

  • absolute(row)
  • afterLast()
  • beforeFirst()
  • first()
  • last()
  • previous()
  • relative(rows)
3.2.6.4 警告の管理

警告は記録されないため、警告を管理するメソッドの挙動は次のようになります。

メソッド挙動
getWarnings()nullを返却
clearWarnings()警告はクリアされない
3.2.6.5 固定値を返す属性

ResultSetがオープンされている間、常に固定の値を返すメソッドのサポート状況は次の通りです。

メソッド結果
getCursorName()nullを返却
getType()TYPE_FORWARD_ONLYを返却
getConcurrency()CONCUR_READ_ONLYを返却
getMetaData()(JDBC準拠)
getStatement()(JDBC準拠)
3.2.6.6 型変換

指定のカラムの値を取得する際、ResultSetが保持する型と求める型とが異なる場合は、次の組み合わせに限り型変換を試みます。

変換先のJava型BOOLINTEGRAL ※1FLOATING ※2TIMESTAMPSTRINGBLOB
boolean○○ ※4○ ※3
byte○○○○
short○○○○
int○○○○
long○○○○
float○○○
double○○○
byte[]○○○○
java.sql.Date○ ※5○
Time○ ※5○
Timestamp○ ※5○
String○○○○○○ ※6
Blob○ ※6○
Object○○○○○○
  • (※1). INTEGRAL: BYTE/SHORT/INTEGER/LONGのいずれか
  • (※2). FLOATING: FLOAT/DOUBLEのいずれか
  • (※3). 変換元文字列が'false'ならばfalseに、'true'ならばtrueに変換する。ASCIIの大文字小文字は同一視する。それ以外は変換できずエラーとなる
  • (※4). 変換元数値が0ならばfalseに、0以外ならばtrueに変換する
  • (※5). 以下のルールで文字列表現の時刻を変換する。
    • 表現をjava.text.SimpleDateFormatと同様のパターン文字列であらわしたものは次の通り。ただしタイムゾーンを除く
      • yyyy-MM-dd'T'HH:mm:ss.SSS
      • yyyy-MM-dd'T'HH:mm:ss
      • yyyy-MM-dd HH:mm:ss.SSS
      • yyyy-MM-dd HH:mm:ss
      • yyyy-MM-dd
      • HH:mm:ss.SSS
      • HH:mm:ss
    • タイムゾーンについては、文字列に含まれるものを優先し、指定のjava.util.Calendar指定時はその内容を参照する。タイムゾーン文字列としては、java.text.SimpleDateFormatの「z」または「Z」パターンで解釈できる表現のほか、UTCであることを示す「Z」表現を受け付ける。タイムゾーン情報が存在しない場合は、システム設定によらずUTCとみなされる
  • (※6). 16進数バイナリ表現とみなして、文字列とBLOBを相互に変換する。ASCIIの大文字小文字は同一視する。それ以外は変換できずエラーとなる
3.2.6.7 カラムの値取得

サポートされている型変換先の型と対応するメソッドより、カラムの値を取得できます。カラムの指定方法としては、カラムラベルとカラムインデックスの両方をサポートします。その他、次の機能を使用できます。

  • getBinaryStream
    • byte[]への型変換結果に相当します
  • wasNull
    • JDBC準拠
3.2.6.8 エラー処理
  • 不正なカラムインデックス
    • 不正なカラムインデックスを指定して値を取得しようとした場合、JDBC_COLUMN_INDEX_OUT_OF_RANGEエラーからなるSQLExceptionが発生します。
  • 型変換エラー
    • 型変換に失敗した場合、JDBC_VALUE_TYPE_CONVERSION_FAILEDエラーからなるSQLExceptionが発生します。
3.2.6.9 未サポートの機能

次のオプション機能は未サポートです。引数を省略しているものは、全てのオーバーロードが未サポートです。

  • cancelRowUpdates()
  • getArray
  • getAsciiStream
  • getBigDecimal
  • getClob
  • getNClob
  • getNCharacterStream
  • getNString
  • getObject(columnIndex, map)
  • getObject(columnLabel, map)
  • getObject(columnIndex, type)
  • getObject(columnLabel, type)
  • getRef
  • getRow()
  • getRowId
  • getSQLXML
  • getUnicodeStream
  • getURL
  • moveToInsertRow()
  • moveToCurrentRow()
  • refreshRow()
  • rowInserted()
  • rowDeleted()
  • rowUpdated()
  • insertで始まる全メソッド
  • updateで始まる全メソッド
  • deleteで始まる全メソッド

3.2.7 ResultSetMetaDataインターフェース

3.2.7.1 カラムの型

ResultSetMetaDataが返却するカラムの型について説明します。ここでは、DatabaseMetaData#getTypeInfo()が返却する型名を基準として説明します。カラムの型を取得する各種メソッドの仕様は次の通りです。

型名getColumnClassNamegetColumnTypegetColumnTypeName
BOOL"java.lang.Boolean"Types#BIT"BOOL"
BYTE"java.lang.Byte"Types#TINYINT"BYTE"
SHORT"java.lang.Short"Types#SMALLINT"SHORT"
INTEGER"java.lang.Integer"Types#INTEGER"INTEGER"
LONG"java.lang.Long"Types#BIGINT"LONG"
FLOAT"java.lang.Float"Types#FLOAT"FLOAT"
DOUBLE"java.lang.Double"Types#DOUBLE"DOUBLE"
TIMESTAMP"java.util.Date"Types#TIMESTAMP"TIMESTAMP"
STRING"java.lang.String"Types#VARCHAR"STRING"
BLOB"java.sql.Blob"Types#BLOB"BLOB"
UNKNOWN ※1"java.lang.Object"Types#OTHER"UNKNOWN"
  • (※1). UNKNOWN:「SELECT NULL」を実行して得られるResultSetのように、カラム型を特定できない場合に使用されます
3.2.7.2 単純値を返す属性
メソッド名結果
getCatalogName""
getColumnDisplaySizeInteger#MAX_VALUE
getPrecision0
getScale0
getSchemaName""
getTableName""
isAutoIncrementfalse
isCaseSensitivetrue
isCurrencyfalse
isDefinitelyWritabletrue
isNullable※1
isReadOnlyfalse
isSearchabletrue
isSignedfalse
isWritabletrue
  • (※1). 演算結果によってcolumnNullable(=1)またはcolumnNoNulls(=0)のいずれかを取ります

4 サンプル

JDBCのサンプルプログラムは以下のとおりです。 

// sample2が実行されている必要があります。
package test;

import java.sql.*;

public class SampleJDBC {
        public static void main(String[] args) throws SQLException {
                if (args.length != 5) {
                        System.err.println(
                                "usage: java SampleJDBC (multicastAddress) (port) (clusterName) (user) (password)");
                        System.exit(1);
                }

                // urlは"jdbc:gs://(multicastAddress):(portNo)/(clusterName)"形式
                String url = "jdbc:gs://" + args[0] + ":" + args[1] + "/" + args[2];
                String user = args[3];
                String password = args[4];

                System.out.println("DB Connection Start");

                // GridDBクラスタとの接続
                Connection con = DriverManager.getConnection(url, user, password);
                try {
                        System.out.println("Start");
                        Statement st = con.createStatement();
                        ResultSet rs = st.executeQuery("SELECT * FROM point01");
                        ResultSetMetaData md = rs.getMetaData();
                        while (rs.next()) {
                                for (int i = 0; i < md.getColumnCount(); i++) {
                                        System.out.print(rs.getString(i + 1) + "|");
                                }
                                System.out.println("");
                        }
                        rs.close();
                        System.out.println("End");
                        st.close();
                } finally {
                        System.out.println("DB Connection Close");
                        con.close();
                }
        }
}