1. KVLocalクイック・スタート
  2. JavaアプリケーションへのKVLocalの埋込み

JavaアプリケーションへのKVLocalの埋込み

アプリケーションのCLASSPATHにkvstore.jarファイルがあることを確認してください。kvstore.jarファイルは、Oracle NoSQL Databaseソフトウェアの一部として入手できます。これはOracle Technology Networkからダウンロードできます。

KVLocalConfigオブジェクトの作成

KVLocalConfigクラスのオブジェクトを作成します。このクラスでは、KVLocalで使用される構成パラメータが表されます。KVLocalConfigクラスには、InetBuilderおよびUnixDomainBuilderという2つのビルダーが含まれています。InetBuilderは、TCP/IPソケットを使用してKVLocalConfigインスタンスを構築するビルダーであり、UnixDomainBuilderは、Unixドメイン・ソケットを使用してKVLocalConfigインスタンスを構築するビルダーです。

KVLocalでは、次の構成パラメータがサポートされています。
パラメータ 説明
StoreName

設定しない場合は、デフォルトでkvstoreになります。

次に例を示します。
  • InetBuilder.setStoreName("nosql")
  • UnixDomainBuilder.setStoreName("nosql")
 KVLocalインスタンスの名前。
HostName

(InetBuilderの場合)設定しない場合は、デフォルトでlocalhostになります。

(UnixDomainBuilderの場合)デフォルトでunix_domain:<KVROOT>/sockets/sockになり、変更はできません。

例: InetBuilder.setHostName("nosql.app.com");

 KVLocalインスタンス用にInetBuilderを使用している場合の、ホストへのアクセスに使用するネットワーク・アドレス。UnixDomainBuilderを使用している場合、このパラメータは設定できません。
Port

設定しない場合は、デフォルトで5000になります。

例: InetBuilder.setPort(5500);

 クライアントのAPIとKVLocalインスタンスとの通信に使用するTCP/IPポート。このパラメータは、InetBuilderを使用している場合のみ変更できます。これは、Unixドメイン・ソケットを使用している場合はTCP/IPポートを表しません。ただし、管理CLIに接続する場合は、デフォルト値5000を-portフラグとともに指定する必要があります。
enableSecurity

(InetBuilderの場合)設定しない場合は、デフォルトでtrueになります。

(UnixDomainBuilderの場合)デフォルトでfalseになり、変更はできません。

例: InetBuilder.enableSecurity(false);

 セキュアなKVLocalストアか非セキュアなKVLocalストアかを指定します。UnixDomainBuilderの場合、このパラメータの値は必ずfalseであり、変更はできません。これは、Unixドメイン・ソケットの構成が通信において本質的にセキュアであるためです。
StorageSize

設定しない場合は、デフォルトで10になります。

例: 記憶域のサイズを80 GBに設定するには
  • InetBuilder.setStorageSize(80);
  • UnixDomainBuilder.setStorageSize(80);
 KVLocalデータベース用に使用可能なディスク領域の最大量(GB)。KVLocalデータベースのディスク使用量がしきい値(5 GBの空き領域を除く)を超えている場合は、十分なデータを削除してしきい値の要件を満たすまで、KVLocalにより、ホスト・システム上のすべての書込み操作が一時停止されます。ストレージ・ディレクトリ・サイズを0に設定した場合、KVLocalでは、5 GBの空きディスク領域を除く使用可能なすべての領域が状況に応じて使用されます。
MemoryMB

設定しない場合は、デフォルトで8192になります。このパラメータの最小値は48です。

例: メモリー・サイズを85 MBに設定するには
  • InetBuilder.setMemoryMB(85);
  • UnixDomainBuilder.setMemoryMB(85);
 埋込みKVLocalデータベースの実行に使用するJavaヒープのメモリー・サイズの量 (MB)。ここでのJavaヒープ・サイズは、アプリケーションを実行しているJVMプロセスではなく、子プロセスのJavaヒープ・サイズを表しています。

ノート:

ホスト・マシンの使用可能メモリーが、リクエストしたヒープ・サイズでJVMを作成するのに十分な量であることを確認してください。
  • セキュアなKVLocalの場合
    import oracle.kv.KVLocalConfig;
/* Create a KVLocalConfig object with TCP sockets */
KVLocalConfig config = new KVLocalConfig.InetBuilder("rootDir")
                        .build();
  • 非セキュアなKVLocalの場合
    import oracle.kv.KVLocalConfig;
/* Create a KVLocalConfig object with port number 6000 and security not enabled */
KVLocalConfig config = new kvlocalConfig.InetBuilder("rootDir")
                        .setPort(6000)
                        .enableSecurity(false)
                        .build();

rootDirとは、kvrootディレクトリがある場所です。これは、Oracle NoSQL Databaseデータが格納されているディレクトリへの絶対パス(/home/kvstoreなど)を示しています。

KVLocalのセキュリティを有効にした場合は、KVLocalを起動すると、kvrootディレクトリの下にセキュリティ・ファイル(user.security)が生成されます。KVストアがすでに存在する場合(つまり、kvrootディレクトリがすでに存在する場合)は、KVLocalにより、既存のkvrootディレクトリにあるセキュリティ・ファイルが使用されてkvstoreが保護されます。 

import oracle.kv.KVLocalConfig;
/* Create a KVLocalConfig object with Unix domain sockets */
KVLocalConfig config = new KVLocalConfig.UnixDomainBuilder("rootDir")
                        .build();

rootDirとは、kvrootディレクトリがある場所です。これは、Oracle NoSQL Databaseデータが格納されているディレクトリへの絶対パス(/home/kvstoreなど)を示しています。

Unixドメイン・ソケットを使用している場合は、ソケット・ファイルがkvrootディレクトリの下に作成されます。これらのソケット・ファイルは、サーバー(KVLocal)とクライアント(ユーザー・アプリケーション)との通信に使用されます。たとえば、kvrootディレクトリが/home/kvrootである場合、このようなUnixドメイン・ソケット・ファイルへのフルパスは/home/kvroot/sockets/sock-5000のようになります。

KVLocal起動APIおよび停止APIの呼出し

KVLocalクラスでは、埋込みNoSQLデータベース・インスタンスを起動または停止するためのAPIが提供されます。アプリケーションで、起動APIまたは停止APIを呼び出し、KVストアに対するハンドルを取得します。

ノート:

1つのアプリケーション(つまり、1つのJVM)で、1つのKVLocalストアのみを管理できます。同じJVMで2つ目のKVLocalをインスタンス化しようとすると、「The KVLocal has already been initialized」という例外がスローされます。
KVLocalクラスでは、KVLocalインスタンスの起動または停止、およびKVストアに対するハンドルの取得のための、次のAPIが提供されます。
メソッド名 説明
start(KVLocalConfig config) KVLocalインスタンスを起動します。
startExistingStore(String rootDir) 既存のルート・ディレクトリからKVLocalインスタンスを起動します。
stop() 実行中のKVLocalインスタンスを停止します。
KVStore getStore() 実行中のKVLocalインスタンスに対するストア・ハンドルを取得します。

このメソッドの初回コール時に、必要に応じて、新しいストア・ハンドルが作成されます。後続のすべてのコールでは、既存のストア・ハンドルが返されます。既存のストア・ハンドルがKVLocal.closeStore()メソッドの起動によってクリーン・アップされている場合は、このメソッドの次回コール時に、新しいストア・ハンドルが再度作成されます。

ノート:

アプリケーションで、ストアへのアクセスが完了したときにKVLocal.closeStore()メソッドを呼び出して、ストア・ハンドルに関連付けられているリソースを解放する必要があります。KVStore.close()メソッドは呼び出さないでください。これを実行すると、ストア・ハンドルに関連付けられているすべてのリソースが解放されず、ストア・ハンドルが機能しなくなります。 
import oracle.kv.KVLocalConfig;
import oracle.kv.KVLocal;
/* Create a KVLocal object and pass the KVLocal configuration parameters to the object */
KVLocalConfig config = new KVLocalConfig.InetBuilder("rootDir")
                        .build();
/* Start KVLocal*/
KVLocal local = KVLocal.start(config);
/* Get a handle to kvstore */
KVStore storeHandle = local.getStore();
/* Use existing key/value APIs to write to kvstore */
storeHandle.put(Key,Value);
ValueVersion valueVersion = storeHandle.get(Key.createKey(key));
/* Close kvstore */
KVLocal.closeStore();
/* Stop kvstore */
local.stop();

rootDirとは、kvrootディレクトリがある場所です。これは、Oracle NoSQL Databaseデータが格納されているディレクトリへの絶対パス(/home/kvstoreなど)を示しています。 

import oracle.kv.KVLocalConfig;
import oracle.kv.KVLocal;
/* Create a KVLocal object and pass the KVLocal configuration parameters to the object */
KVLocalConfig config = new KVLocalConfig.UnixDomainBuilder("rootDir")
                        .build();
/* Start KVLocal*/
KVLocal local = KVLocal.start(config);
/* Get a handle to kvstore */
KVStore storeHandle = local.getStore();
/* Use existing key/value APIs to write to kvstore */
storeHandle.put(Key,Value);
ValueVersion valueVersion = storeHandle.get(Key.createKey(key));
/* Close kvstore */
KVLocal.closeStore();
/* Stop kvstore */
local.stop();

rootDirとは、kvrootディレクトリがある場所です。これは、Oracle NoSQL Databaseデータが格納されているディレクトリへの絶対パス(/home/kvstoreなど)を示しています。