Postgres は拡張可能なデータベースシステ ムです。問い合わせから呼び出すことができる、独自の関数をバックエン ドに追加することができます。独自の型さえも追加することができます。
こういった独特な機構がありますので、Java でもこれを API の拡張セットを用意してサポートします。実際、 標準ドライバの中核でも、ラージオブジェクトなどの実装のためにこの拡 張を使用しています。
拡張機能へのアクセス
いくつかの拡張 API にアクセスするには、postgresql.Connection クラス
の追加メソッドのいくつかを使用しなければなりません。この場合、
Driver.getConnection() からの戻り値をキャストしなければなりません。
例:
Connection db = Driver.getConnection(url,user,pass);
// later on
Fastpath fp = ((postgresql.Connection)db).getFastpathAPI();
Class postgresql.Connection
java.lang.Object
|
+----postgresql.Connection
public class Connection extends Object implements Connection
拡張 API にアクセスするために使用される追加メソッドがあります。
java.sql.Connection で定義されたメソッドは示しません。
public Fastpath getFastpathAPI() throws SQLException
現在の接続用の Fastpath API を返します。
注意 : これは JDBC の一部ではありませんが、
これによって、postgresql のバックエンド自身が持つ関数にアクセ
スすることができます。
主に LargeObject API で使用されます。
この関数を使用する最善の方法は次のようなものです。
import postgresql.fastpath.*;
...
Fastpath fp = ((postgresql.Connection)myconn).getFastpathAPI();
ここで、myconn は開いているpostgresqlへのConnection オブジェクトです。
戻り値:
postgresql バックエンドにある関数へのアクセスを可能にする
Fastpath オブジェクト
例外: SQLException
Fastpath の初回の初期化時に 投げられる可能性があります
public LargeObjectManager getLargeObjectAPI() throws SQLException
現在の接続用のラージオブジェクト API
を返します。
注意: これは JDBC の一部ではありませんが、
これを使って postgresql バックエンド自体にある関数にアクセス
できます。
この関数の最善の使用方法は以下のものです。
import postgresql.largeobject.*;
...
LargeObjectManager lo =
((postgresql.Connection)myconn).getLargeObjectAPI();
ここで、myconn は開いている postgresql への Connection
オブジェクトです。
戻り値:
API を実装した LargeObject オ
ブジェクト
例外: SQLException
LargeObject の初回の初期化時に投げられる可能性があ
ります
public void addDataType(String type,
String name)
これによってクライアントのコードが、多くの postgresql 独特の
データ型の 1 つ用のハンドラを追加することができます。通常、
ドライバで認識されないデータ型は、PGobject インスタンスとして
ResultSet.getObject() から返されます。
このメソッドを使って、PGobject を拡張したクラスを書くことや、
ドライバに型名と使用するクラス名を通知することができます。
この欠点は、接続を確立する度にこのメソッドを呼び出さなければ
ならないことです。
注意: これは JDBC の一部でなく、拡張です。
この関数を使用する最善の方法は次のようなものです。
...
((postgresql.Connection)myconn).addDataType("mytype","my.class.name"-
);
...
ここで、myconn は開いている postgresql への Connection
オブジェクトです。
取り扱うクラスは postgresql.util.PGobject を継承する必要
があります。
Fastpath
Fastpath は libpq C インタフェース内に存在する API
で、これによってクライアントマシンはデータベースバックエンドにある関
数を実行することができます。ほとんどのクライアントコードでは、このメ
ソッドを使用する必要がありません。しかし、ラージオブジェクト
API にて使用しますので、用意されています。
使用するためには、次の行のように postgresql.fastpath パッケージをイン
ポートしなければなりません。
import postgresql.fastpath.*;
そして、FastPath オブジェクトを入手したい時に次のコードを書きます。
これはデータベース接続に関連づいた、コマンドを発行する際に使用する
インスタンスを返します。getFastpathAPI() は
JDBC のメソッドではなく、独自のメソッドですので、
Connection オブジェクトを postgresql.Connection オブジェクトにキャ
ストすることが必要です。
Fastpath インスタンスを所有すれば、fastpath() メソッドを使用してバッ
クエンドの関数を実行することができます。
Class postgresql.fastpath.Fastpath
java.lang.Object
|
+----postgresql.fastpath.Fastpath
public class Fastpath
extends Object
このクラスは Fastpath API を実装します。
これは postgresql のバックエンドにある関数を Java アプリケーショ
ンから実行するための手段です。
src/interfaces/libpq/fe-exec.c ファイルを元に作成しています。
参照
FastpathFastpathArg, LargeObject
メソッド
public Object fastpath(int fnid,
boolean resulttype,
FastpathArg args[]) throws SQLException
関数呼び出しを PostgreSQL バックエンドに送ります。
パラメータ:
fnid - 関数 ID
resulttype - 結果が整数ならば真、その他の場合は偽
args - fastpath に渡す FastpathArguments
戻り値:
データが無い場合、null、整数の結果ならば Integer 型、
さもなくば byte[]
例外: SQLException
データベースアクセスエラーが発生した場合
public Object fastpath(String name,
boolean resulttype,
FastpathArg args[]) throws SQLException
名前によって PostgreSQL バックエンドに関数呼び出しを送ります。
注意:
プロシージャ名の関数 ID への割り当ては、通常は事前に
addfunction() を呼び出して、存在しなければなりません。
関数 ID はバックエンドのバージョンによって異なりますの
で、このメソッドの呼び出しは推奨されています。このメソ
ッドの使用例については postgresql.LargeObject を参照し
て下さい。
パラメータ:
name - 関数名
resulttype - 結果が整数ならば真、さもなくば偽
args - fastpath に渡す FastpathArguments オブジ
ェクト
戻り値:
データが無ければ null、整数の結果であれば Integer 型、
さもなくば byte[]
例外: SQLException
引数 name が未知、または、データベースアクセスエラー
の場合
参照:
LargeObject
public int getInteger(String name,
FastpathArg args[]) throws SQLException
この簡易メソッドは結果の値が整数であることを仮定してい
ます。
パラメータ:
name - 関数名
args - 関数への引数
戻り値:
整数の結果
例外: SQLException
データベースアクセスエラーが発生した、または、結果
が無い場合
public byte[] getData(String name,
FastpathArg args[]) throws SQLException
この簡易メソッドは結果の値がバイナリデータであると仮定し
ています。
パラメータ:
name - 関数名
args - 関数への引数
戻り値:
結果を持つbyte[] 配列
例外: SQLException
データベースアクセスエラーが発生した、または、結
果が無い場合
public void addFunction(String name,
int fnid)
これは関数を検索テーブルに追加します。
ユーザコードは addFunctions メソッドを使用しなければなり
ません。このメソッドは oid を直接記述しておらず問い合わせ
に基づいたものです。関数の oid は静的のままであることは保
証されていませんし、同一のバージョンのサーバ間でさえも異な
ります。
パラメータ:
name - 関数名
fnid - 関数 ID
public void addFunctions(ResultSet rs) throws SQLException
このメソッドは 2 つのカラムを持つ ResultSet を引数とし
てとります。カラム 1 は関数名、カラム 2 は oid を持ちま
す。
ResultSet 全体を読み取り、その値を関数テーブル中に読み込
みます。
このメソッドを呼び出した後に resultset を close() するこ
とを忘れないで下さい。
関数名の検索に関する実装時の注意書き:
PostgreSQL は関数 ID と ID に対応する名前を pg_proc テー
ブルに保存します。ローカルに処理速度を上げるために、要求
に応じてこのテーブルに関数を問い合わせるのではなく
Hashtable が使用されています。また、関数の必須項目のみが
このテーブルに登録されていますので、接続を維持しておくこ
とでできるだけ処理速度を向上させます。
postgresql.LargeObject クラスはその起動時に問い合わせを
行ない、この段階で返された ResultSet を addFunctions()
メソッドに渡します。
これを行なった後、LargeObject API はその関数を名前で参照
します。
手作業による oid への変換ができるとは考えないで下さい。
いいですか。これらは現時点のものです。開発を通して変更
されます。（V7.0でもこの問題について議論が何回かありま
した。）ですから、これは将来の不当な問題を防ぐために実
装されています。
パラメータ:
rs - ResultSet
例外: SQLException
データベースアクセスエラーが発生した場合
参照:
LargeObjectManager
public int getID(String name) throws SQLException
このメソッドは名前に関連付けられた関数 ID を返します。
addFunction() もしくは addFunctions() がこの名前を使っ
て呼び出されていなければ、SQLException が投げられます。
パラメータ:
name - 検索対象となる関数名
戻り値:
fastpath 呼び出し用の関数ID
例外: SQLException
関数が未知である場合
Class postgresql.fastpath.FastpathArg
java.lang.Object
|
+----postgresql.fastpath.FastpathArg
public class FastpathArg extends Object
各 fastpath 呼び出しは引数の配列、引数の数、呼び出される関数に依
存する型を必要とします。
このクラスはこの能力を提供するために必要なメソッドを実装します。
このクラスの使用例については、postgresql.largeobject パッケージを
参照して下さい。
参照:
Fastpath, LargeObjectManager, LargeObject
コンストラクタ
public FastpathArg(int value)
整数値からなる引数で構築します。
パラメータ:
value - 設定する整数値
public FastpathArg(byte bytes[])
byte 型の配列からなる引数で構築します。
パラメータ:
bytes - 保存する配列
public FastpathArg(byte buf[],
int off,
int len)
byte 型の配列の一部からなる引数で構築します。
パラメータ:
buf - 元となる配列
off - 配列内のオフセット
len - 含めるべきデータ長
public FastpathArg(String s)
文字列からなる引数で構築します。
パラメータ:
s - 保存する文字列
地理的データ型
PostgreSQL は、地理的な特徴をテーブルに保存できるデータ型の集合を
持ちます。これらは 1 つの点、線、多角形を扱います。Java では
postgresql.geometric パッケージを使用してこれらの型をサポートしま
す。ここには postgresql.util.PGobject クラスを継承したクラスがあり
ます。どのように独自のデータ型ハンドラを実装するのかについての詳細
はこのクラスを参照して下さい。
Class postgresql.geometric.PGbox
java.lang.Object
|
+----postgresql.util.PGobject
|
+----postgresql.geometric.PGbox
public class PGbox extends PGobject implements Serializable,
Cloneable
このクラスは postgresql における box データ型を表します。
変数
public PGpoint point[]
ボックスの角を示す 2 つの点があります。
Constructors
public PGbox(double x1,
double y1,
double x2,
double y2)
パラメータ:
x1 - 1 番目の x 座標
y1 - 1 番目の y 座標
x2 - 2 番目の x 座標
y2 - 2 番目の y 座標
public PGbox(PGpoint p1,
PGpoint p2)
パラメータ:
p1 - 1 番目の点
p2 - 2 番目の点
public PGbox(String s) throws SQLException
パラメータ:
s - PostgreSQL 構文によるボックス定義
例外: SQLException
定義が無効であった場合
public PGbox()
必須のコンストラクタ。
メソッド
public void setValue(String value) throws SQLException
このメソッドはこのオブジェクトの値を設定します。これは
サブクラスでオーバライドしなければなりませんが、サブク
ラスからも呼び出されます。
パラメータ:
value - このオブジェクトの値の文字列表現
例外: SQLException
値がこの型では無効であった場合
オーバライド:
PGobject クラスの setValue
public boolean equals(Object obj)
パラメータ:
obj - 比較するオブジェクト
戻り値:
2 つのボックスが同一ならば真
オーバライド:
PGobject クラスの equals
public Object clone()
このメソッドはオブジェクトの複製を可能にするためにオーバ
ライドする必要があります。
オーバライド:
PGobject クラスの clone
public String getValue()
戻り値:
postgresql で期待された構文で表した PGbox
オーバライド:
PGobject クラスのgetValue
Class postgresql.geometric.PGcircle
java.lang.Object
|
+----postgresql.util.PGobject
|
+----postgresql.geometric.PGcircle
public class PGcircle extends PGobject implements Serializable,
Cloneable
このクラスは、postgresql の、点と半径からなる circle データ
型を表します。
変数
public PGpoint center
中心点です。
public double radius
半径です。
コンストラクタ
public PGcircle(double x,
double y,
double r)
パラメータ:
x - 中心座標
y - 中心座標
r - 円の半径
public PGcircle(PGpoint c,
double r)
パラメータ:
c - 円の中心を示す PGpoint
r - 円の半径
public PGcircle(String s) throws SQLException
パラメータ:
s - PostgreSQL の構文で表した円の定義
例外: SQLException
変換に失敗した場合
public PGcircle()
ドライバによって使用されるコンストラクタ
メソッド
public void setValue(String s) throws SQLException
パラメータ:
s - PostgreSQL の構文で表した円の定義
例外: SQLException
変換に失敗した場合
オーバライド:
PGobject クラスの setValue
public boolean equals(Object obj)
パラメータ:
obj - 比較するオブジェクト
戻り値:
2 つの円が同一ならば真
（訳注: boxesをcirclesの間違いとして訳。）
オーバライド:
PGobject クラスの equals
public Object clone()
このメソッドはオブジェクトの複製を可能にするためにオーバ
ライドする必要があります。
オーバライド:
PGobject クラスの clone
public String getValue()
戻り値:
postgresql で期待される構文で表した PGcircle
オーバライド:
PGobject クラスの getValue
Class postgresql.geometric.PGline
java.lang.Object
|
+----postgresql.util.PGobject
|
+----postgresql.geometric.PGline
public class PGline extends PGobject implements Serializable,
Cloneable
このクラスは 2 点から構成される線を実装します。今のところまだ、
線はバックエンド内で実装されていませんが、このクラスはバックエ
ンドでの実装がなされればすぐに使えることを保証します。
変数
public PGpoint point[]
2 つの点があります。
コンストラクタ
public PGline(double x1,
double y1,
double x2,
double y2)
パラメータ:
x1 - 1 番目の座標
y1 - 1 番目の座標
x2 - 2 番目の座標
y2 - 2 番目の座標
public PGline(PGpoint p1,
PGpoint p2)
パラメータ:
p1 - 1 番目の点
p2 - 2 番目の点
public PGline(String s) throws SQLException
パラメータ:
s - PostgreSQLの構文で表した線の定義
（訳注: circleをlineの間違いとして訳）
例外: SQLException
変換に失敗した場合
public PGline()
ドライバで必要とされます。
メソッド
public void setValue(String s) throws SQLException
パラメータ:
s - PostgreSQLの構文で表した線分の定義
例外: SQLException
変換に失敗した場合
オーバライド:
PGobject クラスの setValue
public boolean equals(Object obj)
パラメータ:
obj - 比較するオブジェクト
戻り値:
2 つの線が同一ならば真
（訳注: boxesをlinesの間違いとして訳。）
オーバライド:
PGobject クラスの equals
public Object clone()
このメソッドはオブジェクトの複製を可能にするためにオーバ
ライドする必要があります。
オーバライド:
PGobject クラスの clone
public String getValue()
戻り値:
postgresql で期待される構文で表した PGline
オーバライド:
PGobject クラスの getValue
Class postgresql.geometric.PGlseg
java.lang.Object
|
+----postgresql.util.PGobject
|
+----postgresql.geometric.PGlseg
public class PGlseg extends PGobject implements Serializable,
Cloneable
2 つの点からなる lseg（線分）を実装します。
変数
public PGpoint point[]
2 つの点があります。
コンストラクタ
public PGlseg(double x1,
double y1,
double x2,
double y2)
パラメータ:
x1 - 1 番目の座標
y1 - 1 番目の座標
x2 - 2 番目の座標
y2 - 2 番目の座標
public PGlseg(PGpoint p1,
PGpoint p2)
パラメータ:
p1 - 1 番目の点
p2 - 2 番目の点
public PGlseg(String s) throws SQLException
パラメータ:
s - PostgreSQLの構文で表した線分の定義
（訳注: circleをline segmentの間違いとして訳）
例外: SQLException
変換に失敗した場合
public PGlseg()
ドライバによって必要とされます。
メソッド
public void setValue(String s) throws SQLException
パラメータ:
s - PostgreSQLの構文で表した線分の定義
例外: SQLException
変換に失敗した場合
オーバライド:
PGobject クラスの setValue
public boolean equals(Object obj)
パラメータ:
obj - 比較するオブジェクト
戻り値:
2 つの線分が同一ならば真
（訳注: boxesをline segmentsの間違いとして訳。）
オーバライド:
PGobject クラスの equals
public Object clone()
このメソッドはオブジェクトの複製を可能にするためにオーバ
ライドする必要があります。
オーバライド:
PGobject クラスのclone
public String getValue()
戻り値:
postgresql で期待される構文で表した PGlseg
オーバライド:
PGobject クラスの getValue
Class postgresql.geometric.PGpath
java.lang.Object
|
+----postgresql.util.PGobject
|
+----postgresql.geometric.PGpath
public class PGpath extends PGobject implements Serializable,
Cloneable
経路（閉じている可能性がある複数の線分）を実装します。
変数
public boolean open
開いた経路ならば真、閉じた経路ならば偽。
public PGpoint points[]
この経路を定義する点。
コンストラクタ
public PGpath(PGpoint points[],
boolean open)
パラメータ:
points - 経路を定義するPGpoint
open - 開いた経路ならば真、閉じた経路ならば偽
public PGpath()
ドライバで必要とされます。
public PGpath(String s) throws SQLException
パラメータ:
s - PostgreSQLの構文で表した経路の定義
（circle を path の間違いとして訳）
例外: SQLException
変換に失敗した場合
メソッド
public void setValue(String s) throws SQLException
パラメータ:
s - PostgreSQLの構文で表した経路の定義
例外: SQLException
変換に失敗した場合
オーバライド:
PGobject クラスの setValue
public boolean equals(Object obj)
パラメータ:
obj - 比較するオブジェクト
戻り値:
2 つの経路が同一ならば真
（訳注: boxesをpathesの間違いとして訳。）
オーバライド:
PGobject クラスの equals
public Object clone()
このメソッドはオブジェクトの複製を可能にするためにオーバ
ライドする必要があります。
オーバライド:
PGobject クラスのclone
public String getValue()
postgresql で期待される構文で表した経路を返します。
（polygon を path の間違いとして訳）
オーバライド:
PGobject クラスの getValue
public boolean isOpen()
開いた経路ならば真を返します。
public boolean isClosed()
閉じた経路ならば偽を返します。
public void closePath()
閉じた経路として印をつけます。
public void openPath()
開いた経路として印をつけます。
Class postgresql.geometric.PGpoint
java.lang.Object
|
+----postgresql.util.PGobject
|
+----postgresql.geometric.PGpoint
public class PGpoint extends PGobject implements Serializable,
Cloneable
これは、その座標を double 型で使用している点を除き、
java.awt.Point のある版を実装したものです。
postgresql の point データ型に割り当てます。
変数
public double x
点の X 座標
public double y
点の Y 座標
コンストラクタ
public PGpoint(double x,
double y)
パラメータ:
x - 座標値
y - 座標値
public PGpoint(String value) throws SQLException
主に、その定義に点を含む、他の地理的データ型から呼び出さ
れます。
パラメータ:
value - PostgreSQL の構文で表された点の定義
public PGpoint()
ドライバで必要とされます。
メソッド
public void setValue(String s) throws SQLException
パラメータ:
s - PostgreSQLの構文で表した点の定義
例外: SQLException
変換に失敗した場合
オーバライド:
PGobject クラスの setValue
public boolean equals(Object obj)
パラメータ:
obj - 比較するオブジェクト
戻り値:
2 つの点が同一ならば真
（訳注: boxesをpointsの間違いとして訳。）
オーバライド:
PGobject クラスの equals
public Object clone()
このメソッドはオブジェクトの複製を可能にするためにオーバ
ライドする必要があります。
オーバライド:
PGobject クラスのclone
public String getValue()
戻り値:
postgresql で期待される構文で表した PGpoint
オーバライド:
PGobject クラスの getValue
public void translate(int x,
int y)
点を指定した量分移動します。
パラメータ:
x - x 座標に加える整数量
y - y 座標に加える整数量
public void translate(double x,
double y)
点を指定した量分移動します。
パラメータ:
x - x 座標に加える double 型で示された量
y - y 座標に加える double 型で示された量
public void move(int x,
int y)
点を指定座標に移動します。
パラメータ:
x - 座標（整数）
y - 座標（整数）
public void move(double x,
double y)
点を指定座標に移動します。
パラメータ:
x - 座標（double 型）
y - 座標（double 型）
public void setLocation(int x,
int y)
点を指定座標に移動します。この記述については
java.awt.Point を参照して下さい。
パラメータ:
x - 座標（整数）
y - 座標（整数）
参照:
Point
public void setLocation(Point p)
点を与えられたjava.awt.Pointに移動します。この記述につ
いては java.awt.Point を参照して下さい。
パラメータ:
p - 移動先を示す Point
参照:
Point
Class postgresql.geometric.PGpolygon
java.lang.Object
|
+----postgresql.util.PGobject
|
+----postgresql.geometric.PGpolygon
public class PGpolygon extends PGobject implements Serializable,
Cloneable
PostgreSQL の polygon データ型を実装します。
変数
public PGpoint points[]
多角形を定義する点。
コンストラクタ
public PGpolygon(PGpoint points[])
PGpoint の配列を使用して多角形を生成します。
パラメータ:
points - 多角形を定義する点
public PGpolygon(String s) throws SQLException
パラメータ:
s - PostgreSQL の構文で表した多角形の定義
（circle を polygon の間違いとして訳）
例外: SQLException
変換に失敗した場合
public PGpolygon()
ドライバで必要とされます。
メソッド
public void setValue(String s) throws SQLException
パラメータ:
s - PostgreSQLの構文で表した多角形の定義
例外: SQLException
変換に失敗した場合
オーバライド:
PGobject クラスの setValue
public boolean equals(Object obj)
パラメータ:
obj - 比較するオブジェクト
戻り値:
2 つの多角形が同一ならば真
（訳注: boxesをpolygonsの間違いとして訳。）
オーバライド:
PGobject クラスの equals
public Object clone()
このメソッドはオブジェクトの複製を可能にするためにオーバ
ライドする必要があります。
オーバライド:
PGobject クラスのclone
public String getValue()
戻り値:
postgresql で期待される構文で表した PGpolygon
オーバライド:
PGobject クラスの getValue
ラージオブジェクト
ラージオブジェクトは 標準 JDBC 仕様でサポートさ
れています。しかし、そのインタフェースには制限があり、また、
PostgreSQL で用意される API では、ローカルファイル同様にオブジェク
トの内容にランダムアクセスを行なうことができます。
postgresql.largeobject パッケージは Java に対し、libpq C インタフェ
ースにあるラージオブジェクト API を提供します。
ラージオブジェクトの生成、オープン、削除を扱う LargeObjectManager、
及び、個別のオブジェクトを扱う LargeObject という 2 つのクラスから
構成されています。
Class postgresql.largeobject.LargeObject
java.lang.Object
|
+----postgresql.largeobject.LargeObject
public class LargeObject extends Object
このクラスは postgresql のラージオブジェクトインタフェースを実
装します。
インタフェースの実行に必要な基本的なメソッド、及び、このオブジェクト
用の InputStream と OutputStream クラスの組合せを提供するためのメソ
ッドを提供します。
通常クライアントコードでは、ラージオブジェクトにアクセスするた
めに ResultSet のメソッド getAsciiStream、getBinaryStream、ま
たは getUnicodeStream、もしくは PreparedStatement のメソッド
setAsciiStream、setBinaryStream、または setUnicodeStream を使
用します。
しかし、もっと低レベルなラージオブジェクトへのアクセスが必要
となることがあります。これは JDBC 仕様では
サポートされていません。
どのようにラージオブジェクトへのアクセスを得るかやどうやって生成
するかについては postgresql.largeobject.LargeObjectManager を参照
して下さい。
参照:
LargeObjectManager
変数
public static final int SEEK_SET
ファイルの先頭からシークすることを示します。
public static final int SEEK_CUR
現在位置からシークすることを示します。
public static final int SEEK_END
ファイルの終端からシークすることを示します。
メソッド
public int getOID()
戻り値:
ラージオブジェクトの OID
public void close() throws SQLException
オブジェクトを閉じます。このメソッドを呼び出した後にそ
のオブジェクトのメソッドを呼び出してはいけません。
例外: SQLException
データベースアクセスエラーが発生した場合
public byte[] read(int len) throws SQLException
オブジェクトからデータを一部読みとり、byte[] 型の配
列として返します。
パラメータ:
len - 読みとるバイト数
戻り値:
読みとったデータを持つ byte[] 型の配列
例外: SQLException
データベースアクセスエラーが発生した場合
public void read(byte buf[],
int off,
int len) throws SQLException
オブジェクトからデータの一部分を既存の配列に読み込
みます。
パラメータ:
buf - コピー先の配列
off - 配列内のオフセット
len - 読みとるバイト数
例外: SQLException
データベースアクセスエラーが発生した場合
public void write(byte buf[]) throws SQLException
配列をオブジェクトに書き込む
パラメータ:
buf - 書き込む配列
例外: SQLException
データベースアクセスエラーが発生した場合
public void write(byte buf[],
int off,
int len) throws SQLException
配列の一部のデータをオブジェクトに書き込む。
パラメータ:
buf - コピー元となる配列
off - 配列内のオフセット
len - 書き込むバイト数
例外: SQLException
データベースアクセスエラーが発生した場合
public void seek(int pos,
int ref) throws SQLException
オブジェクト内の現在位置を設定します。
標準 C ライブラリの fseek() 呼び出しに似ています。ラー
ジオブジェクトへのランダムアクセスが可能になります。
パラメータ:
pos - オブジェクト内の位置
ref - SEEK_SET、SEEK_CUR、SEEK_ENDの内の一つ
例外: SQLException
データベースアクセスエラーが発生した場合
public void seek(int pos) throws SQLException
オブジェクト内の現在位置を設定します。
標準 C ライブラリの fseek() 呼び出しに似ています。ラー
ジオブジェクトへのランダムアクセスが可能になります。
パラメータ:
pos - オブジェクト内の先頭からの位置
例外: SQLException
データベースアクセスエラーが発生した場合
public int tell() throws SQLException
戻り値:
オブジェクト内の現在位置
例外: SQLException
データベースアクセスエラーが発生した場合
public int size() throws SQLException
このメソッドは役に立ちません。ですので、オブジェクトの大き
さを探す唯一の方法は終端までシークし、現在位置を記録し、そ
して元の位置に戻すことです。
今後より良いメソッドができます。
戻り値:
ラージオブジェクトの大きさ
例外: SQLException
データベースアクセスエラーが発生した場合
public InputStream getInputStream() throws SQLException
このオブジェクトからの InputStream を返します。
この InputStream インスタンスは、この後に InputStream を
必要とする任意のメソッドに使うことができます
例外: SQLException
データベースアクセスエラーが発生した場合
public OutputStream getOutputStream() throws SQLException
このオブジェクトへの OutputStream を返します。
この OutputStream インスタンスは、この後に OutputStream を
必要とする任意のメソッドに使うことができます
例外: SQLException
データベースアクセスエラーが発生した場合
Class postgresql.largeobject.LargeObjectManager
java.lang.Object
|
+----postgresql.largeobject.LargeObjectManager
public class LargeObjectManager extends Object
このクラスは postgresql のラージオブジェクトインタフェースを実
装します。
クライアントコードにて、ラージオブジェクトの生成、オープン、削除を
可能にするためのメソッドを提供します。オブジェクトを開くと、
postgresql.largeobject.LargeObject のインスタンスが返され、そのイン
スタンスのメソッドを使ってラージオブジェクトにアクセスできます。
このクラスは postgresql.Connection によってのみ作成できます。
このクラスへのアクセスを得るには、次のようなコードの一部を使用します。
import postgresql.largeobject.*;
Connection conn;
LargeObjectManager lobj;
... code that opens a connection ...
lobj = ((postgresql.Connection)myconn).getLargeObjectAPI();
通常クライアントコードでは、ラージオブジェクトにアクセスするた
めに ResultSet のメソッド getAsciiStream、getBinaryStream、ま
たは getUnicodeStream、もしくは PreparedStatement のメソッド
setAsciiStream、setBinaryStream、または setUnicodeStream を使
用します。
しかし、もっと低レベルなラージオブジェクトへのアクセスが必要
となることがあります。これは JDBC 仕様では
サポートされていません。
どのようにラージオブジェクトの内容を扱うのかについては、
postgresql.largeobject.LargeObject を参照して下さい。
参照:
LargeObject
変数
public static final int WRITE
このモードはオブジェクトに書き込みを行なう予定であるこ
とを示します。
public static final int READ
このモードはオブジェクトに読み取りを行なう予定であるこ
とを示します。
public static final int READWRITE
このモードがデフォルトです。オブジェクトに読み取り、及び、
書き込みを行なう予定であることを示します。
public LargeObject open(int oid) throws SQLException
既存のラージオブジェクトを、その OID に基づいて開きます。
このメソッドは （デフォルトである）READ と WRITE アクセ
スが要求されているものと仮定します。
パラメータ:
oid - ラージオブジェクトの oid
戻り値:
そのオブジェクトへのアクセスを提供する
LargeObject インスタンス
例外: SQLException
エラー時
public LargeObject open(int oid,
int mode) throws SQLException
既存のラージオブジェクトを、その OID に基づいて開きます。
パラメータ:
oid - ラージオブジェクトの oid
mode - オープンモード
戻り値:
そのオブジェクトへのアクセスを提供する
LargeObject インスタンス
例外: SQLException
エラー時
public int create() throws SQLException
ラージオブジェクトを作成し、その OID を返します。
新しいオブジェクトの属性のデフォルトは READWRITE です。
戻り値:
新しいオブジェクトの oid
Throws: SQLException
エラー時
public int create(int mode) throws SQLException
ラージオブジェクトを作成し、その OID を返します。
パラメータ:
mode - 新しいオブジェクトの異なった属性を示すビットマスク
戻り値:
新しいオブジェクトの oid
例外: SQLException
エラー時
public void delete(int oid) throws SQLException
ラージオブジェクトを削除します。
パラメータ:
oid - 削除するオブジェクトを示す oid
例外: SQLException
エラー時
public void unlink(int oid) throws SQLException
ラージオブジェクトを削除します。delete メソッドと同一です。こ
れは C API 同様に unlink を使用するために用
意されています。
オブジェクト直列化
PostgreSQL はごく普通の SQL データベースではありません。他のほと
んどのデータベースよりもかなり拡張性があり、特有のオブジェクト指
向機能をサポートしています。
他のテーブルにある行を参照するテーブルを持つことができるということはこ
の結果の1つです。例えば、
test=> create table users (username name,fullname text);
CREATE
test=> create table server (servername name,adminuser users);
CREATE
test=> insert into users values ('peter','Peter Mount');
INSERT 2610132 1
test=> insert into server values ('maidast',2610132::users);
INSERT 2610133 1
test=> select * from users;
username|fullname
--------+--------------
peter |Peter Mount
(1 row)
test=> select * from server;
servername|adminuser
----------+---------
maidast | 2610132
(1 row)
わかりますか。上の例では、テーブルの名前をフィールドとして持つことが
でき、行の oid がそのフィールドに埋め込まれていることを示しています。
Java ではこれをどう扱わなければならないでしょうか?
Java では java.io.Serializable インタフェースを実装するクラスならば
ストリームにオブジェクトを保存することができます。オブジェクト直列化
として知られるこの処理は、複雑なオブジェクトをデータベースに保存する
ことに使用することができます。
さて、JDBC では、それらを保存する際に LargeObject
を使用しなければなりません。しかし、これらのオブジェクトに問い合わせ
を行なうことができません。
postgresql.util.Serialize クラスが行なうことは、オブジェクトをテーブ
ルとして保存する手段、及び、テーブルからオブジェクトを取り出す手段を
提供することです。ほとんどの場合では、このクラスを直接アクセスする必
要はなく、PreparedStatement.setObject() と ResultSet.getObject() メ
ソッドを使うことになります。これらのメソッドはオブジェクトのクラス名
をデータベース内のテーブル名で照合します。合うものがあれば、そのオブ
ジェクトは直列化されたオブジェクトとみなし、そのテーブルから取り出し
ます。その処理の際にそのオブジェクトが直列化された別のオブジェクトを
持つ場合、再帰的にそのツリーを辿ります。
複雑に見えますか？実際は、私が述べたことよりは簡単です。説明すること
が難しいだけです。
このクラスにアクセスする機会は、create() メソッド群を使用する時だけ
です。これらはドライバから使用されるものではありませんが、直列化要
求のあった Java のオブジェクトやクラスに基づいた 1 つ以上の
"create table" 文をデータベースに対して発行します。
さて、これが最後ですが、もし対象とするオブジェクトが、
public int oid;
という行を含むのならば、テーブルからオブジェクトを取り出す際に、そ
こにテーブル内の oid が設定されます。そして、オブジェクトが変更され、
再度直列化されると、既存のエントリは更新されます。
oid 変数がなければ、オブジェクトが直列化された時に常に挿入され、そ
して、テーブルに既存のエントリは全て保存されます。
直列化前に oid 変数を 0 にすると、そのオブジェクトは挿入されるように
なります。これにより、あるオブジェクトをデータベース内に複数持たせる
ことができます。
Class postgresql.util.Serialize
java.lang.Object
|
+----postgresql.util.Serialize
public class Serialize extends Object
このクラスは、Java のオブジェクトを保存するために PostgreSQL のオブ
ジェクト指向機能を使用します。このクラスでは、Java のクラス名をデー
タベース内のテーブルに対応させることでそれを行ないます。この新しい
テーブル各エントリはこのクラスの直列化されたインスタンスを表します。
各エントリは OID（オブジェクト識別子）を持ちますので、この OID を別
のテーブルに持たせることができます。このクラスはここで示すには複雑
過ぎますので、より詳細については主文書にて記載させる予定です。
コンストラクタ
public Serialize(Connection c,
String type) throws SQLException
このメソッドは、PostgreSQL のテーブルからある Java オブ
ジェクトを直列化または復号化するために使用できる、インス
タンスを生成します。
メソッド
public Object fetch(int oid) throws SQLException
指定した OID のオブジェクトをテーブルから入手します。
パラメータ:
oid - オブジェクトの oid
戻り値:
oid に対応するオブジェクト
例外: SQLException
エラー時
public int store(Object o) throws SQLException
テーブルにオブジェクトを保存し、その OID を返します。
そのオブジェクトが OID という名前の整数型変数をもち、それ
が 0 より大きい場合、その値が OID として使われ、テーブルは
更新されます。OID 変数が 0 ならば、新しい行が作成され、行の
OID がそのオブジェクトに設定されます。これにより、データベー
ス内のオブジェクトの値が更新可能になります。オブジェクトが
OID という整数型変数を持たない場合、オブジェクトは保存されま
す。が、その後にそのオブジェクトを取り出し、修正し、再度保存
した場合に、その新しい状態はテーブルに追加され、古いエントリ
を上書きしません。
パラメータ:
o - 保存するオブジェクト（Serializable を実装する必
要があります）
戻り値:
保存したオブジェクトの oid
例外: SQLException
エラー時
public static void create(Connection con,
Object o) throws SQLException
このメソッドはドライバで使われませんが、Serializable を実
装した指定 Java オブジェクトに対応するテーブルを作成します。
オブジェクトの直列化を行なう前に使用しなければなりません。
パラメータ:
c - データベースへの Connection オブジェクト
o - テーブルに基づくオブジェクト
Throws: SQLException
エラー時
Returns:
oidに対応したオブジェクト
（訳注: 間違いです。シグネチャでは void です。）
Throws: SQLException
エラー時
public int store(Object o) throws SQLException
（訳注: 前述されています。）
オブジェクトをテーブルに保存し、その OID を返します。
そのオブジェクトが OID という名前の整数型変数をもち、それ
が 0 より大きい場合、その値が OID として使われ、テーブルは
更新されます。OID 変数が 0 ならば、新しい行が作成され、行の
OID がそのオブジェクトに設定されます。これにより、データベー
ス内のオブジェクトの値が更新可能になります。オブジェクトが
OID という整数型変数を持たない場合、オブジェクトは保存されま
す。が、その後にそのオブジェクトを取り出し、修正し、再度保存
した場合に、その新しい状態はテーブルに追加され、古いエントリ
を上書きしません。
パラメータ:
o - 保存するオブジェクト（Serializable を実装する必
要があります）
戻り値:
保存したオブジェクトの oid
例外: SQLException
エラー時
public static void create(Connection con,
Object o) throws SQLException
（このメソッドも前述されています。）
このメソッドはドライバで使われませんが、Serializable を実
装した指定 Java オブジェクトに対応するテーブルを作成します。
オブジェクトの直列化を行なう前に使用しなければなりません。
パラメータ:
c - データベースへの Connection オブジェクト
o - テーブルに基づくオブジェクト
例外: SQLException
エラー時
public static void create(Connection con,
Class c) throws SQLException
（このメソッドも前述されています。）
このメソッドはドライバで使われませんが、Serializable を実
装した指定 Java オブジェクトに対応するテーブルを作成します。
オブジェクトの直列化を行なう前に使用しなければなりません。
パラメータ:
c - データベースへの Connection オブジェクト
o - テーブルに基づくオブジェクト
例外: SQLException
エラー時
public static String toPostgreSQL(String name) throws SQLException
Java のクラス名を「 . 」を「 _ 」に置換してpostgresql テー
ブルに変換します。
この理由は、クラス名は「 _ 」を持つことができないからです。
他の制限として、（パッケージを含めた）完全なクラス名は 31
文字を越えられないことがあります。（これは PostgreSQL によ
る制限です。）
パラメータ:
name - クラス名
戻り値:
PostgreSQL のテーブル名
例外: SQLException
エラー時
public static String toClassName(String name) throws SQLException
postgresql のテーブルを「 _ 」を「 . 」に置換して Java の
クラス名に変換します。
パラメータ:
name - PostgreSQL テーブル名
戻り値:
クラス名
例外: SQLException
エラー時
ユーティリティクラス
postgresql.util パッケージには主ドライバやその他の拡張機能の内部で使
用されるクラスがあります。
Class postgresql.util.PGmoney
java.lang.Object
|
+----postgresql.util.PGobject
|
+----postgresql.util.PGmoney
public class PGmoney extends PGobject implements Serializable,
Cloneable
PostgreSQL のmoney 型を取り扱うクラスを実装したものです。
変数
public double val
フィールドの値。
コンストラクタ
public PGmoney(double value)
パラメータ:
value - フィールドの値
public PGmoney(String value) throws SQLException
主に、その定義にpoint型を持っている他の地理的データ型から呼
び出されます。
（訳注: 間違いと思われます。PGpoint(String value)の説明が書
いてあります。）
public PGmoney()
ドライバで必要とされます。
メソッド
public void setValue(String s) throws SQLException
パラメータ:
s - PostgreSQL 構文によるこの金額の定義
（訳注: pointはmoneyの間違いとして訳）
例外: SQLException
変換失敗時
オーバライド:
PGobject クラスの setValue
public boolean equals(Object obj)
パラメータ:
obj - 比較するオブジェクト
戻り値:
2つの金額が同一ならば真
（訳注: boxesはmoneysの間違いとして訳）
オーバライド:
PGobject クラスの equals
public Object clone()
このメソッドはオブジェクトの複製を可能にするためにオーバ
ライドする必要があります。
オーバライド:
PGobject クラスのclone
public String getValue()
戻り値:
postgresql で期待される構文で表したPGmoney
（訳注: PGpoint を PGmoney の間違いとして訳）
オーバライド:
PGobject クラスの getValue
Class postgresql.util.PGobject
java.lang.Object
|
+----postgresql.util.PGobject
public class PGobject extends Object implements Serializable,
Cloneable
このクラスは JDBC の標準では未知のデータ型を記
述するために使用されます。
postgresql.Connection への呼び出しでは、指定した型に関連付けられた、
このクラスを継承したクラスを使用することができます。
ResultSet.getObject() はそのハンドラを使って認識できなかった型の場
合、全てこのクラスを返します。これにより任意の postgresql のデータ
型がサポートされます。
コンストラクタ
public PGobject()
オブジェクトを作成する時に postgresql.Connection.getObject()
から呼び出されます。
メソッド
public final void setType(String type)
このメソッドはこのオブジェクトの型を設定します。
サブクラスで継承されてはなりませんので、final メソッドで
す。
パラメータ:
type - オブジェクトの型を示す文字列
public void setValue(String value) throws SQLException
このオブジェクトに値を設定します。オーバライドされな
ければなりません。
パラメータ:
value - そのオブジェクトの値の文字列表現
例外: SQLException
値がこの型で無効だった場合
public final String getType()
このオブジェクトが有効である間に変更することができないよう
に、final とします。
戻り値:
このオブジェクトの型名
public String getValue()
オブジェクトの値をpostgresqlで要求された形式で返すために、
これはオーバライドされなければなりません。
戻り値:
オブジェクトの値
public boolean equals(Object obj)
オブジェクトの比較ができるように、オーバライドされなけれ
ばなりません。
パラメータ:
obj - 比較するオブジェクト
戻り値:
2つのオブジェクトが同一ならば真
（訳注: boxesはobjectsの間違いとして訳）
オーバライド:
Object クラスの equals
public Object clone()
このメソッドはオブジェクトの複製を可能にするためにオーバ
ライドする必要があります。
オーバライド:
Object クラスの clone
public String toString()
ここで定義されています。ユーザのコードでオーバライドする
必要はありません。
戻り値:
postgresql で期待される構文を使ったこのオブジェクトの値。
オーバライド:
Object クラスの toString
Class postgresql.util.PGtokenizer
java.lang.Object
|
+----postgresql.util.PGtokenizer
public class PGtokenizer extends Object
このクラスはpostgresのテキスト出力のトークン化に使用されます。
以前はStringTokenizer を使用していましたが、地理的データ型で使
用される、入れ子状の '(' ')' '[' ']' '<' 及び '>' を扱う必要が
ありました。
主に地理的クラスにて使用されますが、postgresql から生成されるど
のようなカスタムデータ型の出力の解析にも使用できます。
コンストラクタ
public PGtokenizer(String string,
char delim)
トークン化機構を生成します。
パラメータ:
string - トークン化する文字列
delim - トークンをわける 1 つの文字
メソッド
public int tokenize(String string,
char delim)
新しい文字列と区切り文字でトークン化機構をリセット
します。
パラメータ:
string - トークン化する文字列
delim - トークンをわける 1 つの文字
public int getSize()
戻り値:
利用可能なトークン数
public String getToken(int n)
パラメータ:
n - トークン番号 ( 0 ... getSize()-1 )
戻り値:
トークンの値
public PGtokenizer tokenizeToken(int n,
char delim)
トークンの1つに基づく新しいトークン化機構を返します。地理的データ型（通常は PGpoint ）はこれを使用して入れ子状のトークンを処理します。
パラメータ:
n - トークン番号 ( 0 ... getSize()-1 )
delim - 使用する区切り文字
戻り値:
トークンに基づく新しいPGtokenizer インスタンス
public static String remove(String s,
String l,
String t)
文字列の前/後ろの文字列を削除します。
パラメータ:
s - 元となる文字列
l - 前から削除する文字列
t - 後ろから削除する文字列
文字列:
前/後ろの文字列を削除した文字列
public void remove(String l,
String t)
全てのトークンから前/後ろの文字列を削除します。
パラメータ:
l - 前から削除する文字列
t - 後ろから削除する文字列
public static String removePara(String s)
文字列の始めと終りにある ( と ) を削除します。
パラメータ:
s - 削除対象文字列
戻り値:
( と ) を削除した文字列
public void removePara()
全てのトークンの始めと終りにある ( と ) を削除します。
戻り値:
( と ) を削除した文字列
（訳注: シグネチャは void です。）
public static String removeBox(String s)
文字列の始めと終りにある [ と ] を削除します。
パラメータ:
s - 削除対象文字列
戻り値:
[ と ] を削除した文字列
public void removeBox()
全てのトークンの始めと終りにある [ と ] を削除します。
戻り値:
[ と ] を削除した文字列
（訳注: 間違いです。シグネチャは void です。）
public static String removeAngle(String s)
文字列の始めと終りにある < と > を削除します。
パラメータ:
s - 削除対象文字列
戻り値:
< と > を削除した文字列
public void removeAngle()
全てのトークンの始めと終りにある < と > を削除します。
戻り値:
< と > を削除した文字列
（訳注: シグネチャは void です。）
Class postgresql.util.Serialize
このクラスは上のオブジェクト直列化の節にて説明されました。
Class postgresql.util.UnixCrypt
java.lang.Object
|
+----postgresql.util.UnixCrypt
public class UnixCrypt extends Object
このクラスはネットワークに暗号化パスワードを送信する能力を提供し
ます。
暗号化、及び Unix の暗号化パスワードと比較する静的メソッドを持ち
ます。
元となったソースについては、次の John Dumas 氏の Java 暗号ページ
を参照して下さい。
http://www.zeh.com/local/jfd/crypt.html
メソッド
public static final String crypt(String salt,
String original)
指定された平文パスワードと "ソルト" でパスワードを暗号化します。
パラメータ:
salt - 暗号化エンジンを多くの異なった方法で繰り返させ
るために使用するソルトを表した 2 文字の文字列。新
しく暗号を生成したい場合は、この値を乱数化しな
ければなりません。
original - 暗号化対象のパスワード
戻り値:
2 文字のソルトとそれに続く暗号化パスワードからなる
文字列
public static final String crypt(String original)
指定平文パスワードを暗号化します。このメソッドは
'java.util.Random' クラスを使用して乱数化されたソルトを
生成します。
パラメータ:
original - 暗号化対象パスワード
戻り値:
2 文字のソルトとそれに続く暗号化パスワードからなる
文字列
public static final boolean matches(String encryptedPassword,
String enteredPassword)
引数 enteredPasswordを暗号化し、引数 encryptedPassword と
照合します。
パラメータ:
encryptedPassword - 暗号化されたパスワード。最初の
2 文字はソルトと仮定されます。この文字列は Unix
の /etc/passwd ファイルにあるものと同一のものです。
enteredPassword - ユーザが入力した（または別の方法
で入手した）パスワード
戻り値:
パスワードが正しいとみなされた場合、真
複数のスレッド、サーブレット環境におけるドライバの使用
多くの JDBC ドライバでは、ある時点でたった 1 つ
のスレッドだけが Connection オブジェクトを使用できるという問題があ
ります。あるスレッドが結果を受け取っている時に別のスレッドが問い合
わせを送る場合は別です。このことはデータベースエンジンにとって有害
です。
PostgreSQL 6.4 で、ドライバ全体をスレッドセーフにしました。標準
JDBC は 6.3.x の段階でスレッドセーフでしたが、
Fastpath API はそうではありませんでした。
ですので、アプリケーションで複数のスレッドを使用する（ほとんどのまと
もなアプリケーションでそうするでしょう）場合、同時にデータベースを使
用するスレッドがないことを確実にするための複雑な仕組みを考える必要が
ありません。
スレッドが別のスレッドが使用している時に接続を使用しようとすると、他
のスレッドが完了するまでその操作は待たされます。
標準 SQL 文の場合、操作とは文を送信し、何らかの ResultSet を（完全に）
受け取ることです。
Fastpath 呼び出し（つまり LargeObject からブロックを読むこと）の場合、
それはブロックを送信する、または、受け取る瞬間です。
これはアプリケーションやアプレットでは優れていますが、サーブレットの
場合は性能に関する問題を発生させます。
サーブレットでは、その接続に重い負荷をかけることができます。問い合わ
せを行なう複数のスレッドがある場合、それぞれは待たされ、そして、それ
がその次に行なわれるとは限りません
これを解消するために、Connection オブジェクトのプールを作成すること
を勧めます。
あるスレッドがデータベースへの接続を必要とした時には常に、
Connection オブジェクトを管理するクラスに尋ねます。管理クラスは空きの
接続をそのスレッドに渡し、その接続に使用中と印をつけます。空き接続が
なければ、接続を開きます。
スレッドが処理を終えた段階で、管理クラスに返却します。管理クラスはその
接続を閉じることも、また、プールに追加することもできます。また、管理ク
ラスは接続が現在も有効かどうか点検し、もし無効であればそれをプールから
削除します。
ですので、サーブレットでは、1 つの接続を使用するかプールを使用するかは
設計者に依存します。プールの場合の利点は、そのスレッドが 1 つのネット
ワーク接続が原因となるボトルネックの影響を受けないことです。欠点は、バ
ックエンドプロセスが各接続用に生成されますので、サーバの負荷が増大する
ことです。
設計者、そしてそのアプリケーションの要求仕様に依存します。