Red Hat Database is more extensible than most other databases and supports unique object-oriented features. One of the consequences of this is that you can have one table refer to a row in another table. For example:
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) |
The above shows that we can use a table name as a field, and the row's OID value is stored in that field.
With Java, you can convert an object to a Stream as long as its class implements the java.io.Serializable interface. This process, known as Object Serialization, can be used to store complex objects in the database. If JDBC was used, you could use a Large Object to store objects. You cannot, however, perform queries on those objects.
What the org.postgresql.util.Serialize class does is provide a means of storing an object as a table. It also provides methods to retrieve that object from a table. In most cases, you do not need to access this class directly; you would use the PreparedStatement.setObject() and ResultSet.getObject() methods. Those methods check the object's class name against the tables in the database. If a match is found, it assumes that the object is a Serialized object and retrieves it from that table. As it does so, if the object contains other serialized objects, then it retrieves them, continuing on recursively.
The only time you would access this class, is to use the create() methods. These are not used by the driver, but issue one or more "create table" statements to the database, based on a Java Object or Class that you want to serialize.
If your object contains a line such as:
public int oid; |
then, when the object is retrieved from the table, it is set to the oid within the table. Then, if the object is modified and re-serialized, the existing entry is updated.
If the oid variable is not present, then when the object is serialized, it is always inserted into the table and any existing entry in the table is preserved. Setting oid to 0 before serialization will also cause the object to be inserted. This enables an object to be duplicated in the database.
package org.postgresql.util;
public class Serializable {
// Constructors
public Serialize(Connection con, String type)
throws SQLException;
// Methods
public Object fetch(int oid) throws SQLException;
public int store(Object o) throws SQLException;
// Class Methods
public static void create(Connection con, Object o)
throws SQLException;
public static String toClassName(String name)
throws SQLException;
public static String toPostgreSQL(String name)
throws SQLException;
} |
This method creates an instance of Serialize that can be used to serialize/deserialize a Java object to or from a Red Hat Database table.
Parameters.
The database connection to use.
The database connection to use.
This method fetches the object with OID oid from the table set in the Serialize constructor call.
Parameters.
The OID of the object to fetch.
Returns. The object that corresponds to the given OID.
Stores an object into the table set in the Serialize constructor call.
If the object has an public int field called oid, then the following rules apply:
If oid is set to a value larger than 0, then oid is taken as the OID of the row in the table where the object is stored; the table will be updated.
If the value of oid is 0 then a new row will be created and the value of oid will be set in the object the OID of the new row. This enables an object's value in the database to be updatable.
If the object has no int called OID then the object is just stored. However, if the object is later retrieved, modified and then stored again, its new state will be appended to the table; old entries will not be overwritten.
Parameters.
The object to serialize.
Returns. The OID of the row object is stored in.
This method creates a table, given a Serializable Java Object. It should be used before serializing any objects.
Parameters.
The connection to the database.
The object to base the table on.
This converts a Java Class name to a Red Hat Database table, by replacing periods (.) with underscores (_). Thus, a Class name must not have any underscores in the name.
Another limitation is that the entire class name (including packages) cannot be longer than 31 characters (a limit forced by PostgreSQL).
Parameters.
The class name.
Returns. A string that contains the Red Hat Database table name.
This converts a PostgreSQL table to a Java Class name, by replacing underscores (_) with periods (.).
Parameters.
The Red Hat Database table name.
Returns. A string that contains the Java class name.
The PGobject class is used to describe specialized data types that are not included in the JDBC standards. A call to the addDatatype method of an org.postgresql.Connection object permits a class that extends PGobject to be associated with a named type. This is how the org.postgresql.geometric package operates.
ResultSet.getObject() will return a PGobject instance for any type that is not recognized and does not have its own handler. Therefore, all PostgreSQL data types are supported.
package org.postgresql.util;
public class PGobject implements Serializable, Cloneable {
// Constructors
public PGobject();
// Methods
public Object clone();
public boolean equals(Object obj);
public final String getType();
public String getValue();
public final void setType(String type);
public void setValue(String value) throws SQLException;
public String toString();
} |
Creates a new instance of PGobject.
Creates a new PGobject object that is exactly the same as this one.
Compares the current PGobject object with another PGobject object.
Parameters.
object to compare with
Returns the name of the type that this PGobject represents.
Returns the value of the type that this PGobject represents. This method should be overridden by subclasses.
Sets the type of the object.
Parameters.
The name.
Sets the value of this PGobject. This method should be overridden by subclasses.
Parameters.
String representation of this object's value.
Returns the value of this object in string form.
The PGmoney class handles the Red Hat Database money data type.
package org.postgresql.util;
public class PGmoney extends PGobject
implements Serializable, Cloneable {
// Variables
public double val;
// Constructors
public PGmoney();
public PGmoney(double val);
public PGmoney(String value) throws SQLException;
// Methods
public void setValue(String s) throws SQLException;
public boolean equals(Object obj);
public Object clone();
public String getValue();
} |
The monetary amount that the a PGmoney object represents.
Creates a new PGmoney object. The value of val is undefined.
Creates a new PGmoney object with val set to value.
Parameters.
The amount of money the new PGmoney object should represent.
Creates a new PGmoney object using the Red Hat Database syntax for the money data type.
Parameters.
The definition in the Red Hat Database money syntax.
Creates a new PGmoney object that is exactly the same as this one.
Compares the current PGmoney object with another PGmoney object.
Parameters.
The object to compare with.
Returns. True if the two PGmoney objects are identical.
Returns the definition of the PGmoney object in the Red Hat Database money syntax.
Returns. The PGmoney definition in the syntax expected by Red Hat Database.
This method sets the value of this PGmoney object. The Red Hat Database money syntax must be used.
Throws: SQLException on conversion failure.
The PGtokenizer class is used to tokenize the text output of Red Hat Database. It is used by the geometric classes. Any custom handler classes that need to parse output from Red Hat Database will find PGtokenizer useful.
package org.postgresql.util;
public class PGtokenizer {
// Constructors
public PGtokenizer(String string, char delim);
// Methods
public int getSize();
public String getToken(int n);
public void remove(String l, String t);
public void removeAngle();
public void removeBox();
public void removePara();
public int tokenize(String string, char delim);
public PGtokenizer tokenizeToken(int n, char delim);
// Class methods
public static String remove(String s, String l, String t);
public static String removeAngle(String s);
public static String removeBox(String s);
public static String removePara(String s);
} |
Creates a new tokenizer that will tokenize the supplied string using delim as token separator.
Parameters.
The string to tokenize.
The character that separates tokens.
Returns the number of tokens that the string was parsed into.
getToken returns the n'th available token. n is between 0 and getSize() - 1.
Parameters.
Token to get.
Returns. The n'th token.
Removes the String l from the beginning of all tokens and the String t from the end of all tokens.
Parameters.
Leading string to remove.
Trailing string to remove.
Removes '<' from the beginning of all tokens and '>' from the end of all tokens.
Removes '[' from the beginning of all tokens and ']' from the end of all tokens.
Removes '(' from the beginning of all tokens and ')' from the end of all tokens.
Resets the tokenizer with a new string and delimiter.
Parameters.
The string to tokenize.
Character to recognize as the delimiter.
Returns. The number of tokens created.
Returns a new tokenizer based on the n'th token of the current tokenizer, where 0 <= n <= getSize() - 1. This method is useful for parsing nested tokens.
Parameters.
The index of the token to tokenize.
Character to recognize as the delimiter.
Returns. A new PGtokenizer.
Removes the given leading and trailing strings from another string.
Parameters.
The String to be trimmed.
The leading String to remove.
The trailing String to remove.
Returns. A new String based on s but without leading and trailing strings.
Removes '<' from the beginning of s and '>' from the end of s.
Parameters.
The String to trim angled brackets from.
Returns. A new String based on s but with leading '<' removed and trailing '>' removed.
Removes '[' from the beginning of s and ']' from the end of s.
Parameters.
The String to trim square brackets from.
Returns. A new String based on s but with leading '[' removed and trailing ']' removed.
Removes '(' from the beginning of s and ')' from the end of s.
Parameters.
The String to trim parentheses from.
Returns. A new String based on s but with leading '(' removed and trailing ')' removed.
UnixCrypt provides the ability to encrypt passwords that are to be sent over the network stream for user authentication. It contains static methods to encrypt passwords and to compare passwords with Unix-encrypted ones.
package org.postgresql.util;
public class UnixCrypt {
// Class Methods
public static final String crypt(String original);
public static final String crypt(String salt,
String original);
public static final boolean matches(String
encrypted, String entered);
} |
Returns an encrypted version of the original parameter. This method generates and uses a random salt using the java.util.Random class.
Parameters.
The text (password) to encrypt.
Returns. The encrypted version of the original parameter.
Returns an encrypted version of the original parameter. This method uses a user-supplied salt value.
Parameters.
A two-character string representing the salt that is used to iterate the encryption engine in many different ways. If you are generating a new encryption, this should be set to a random value.
The text (password) to encrypt.
Returns. The encrypted version of the original parameter.
Checks that enteredPassword encrypts to encryptedPassword.
Parameters.
The encrypted text. The first two characters are assumed to be the salt. This string would be the same one as found in a Unix /etc/passwd file.
The text plain text that is being checked.
Returns. Returns true when enteredPassword encrypts to encryptedPassword; false otherwise
This implements a version of java.awt.Point, except it uses double variables to represent the coordinates. PGpoint maps to the point data type in Red Hat Database.
package org.postgresql.geometric;
public class PGpoint extends PGobject
implements Serializable, Cloneable {
// Variables
public double x;
public double y;
// Constructors
public PGpoint();
public PGpoint(double x, double y);
public PGpoint(String value) throws SQLException;
// Methods
public Object clone();
public boolean equals(Object obj);
public String getValue();
public void move(int x, int y);
public void move(double x, double y);
public void setLocation(int x, int y);
public void setLocation(Point p);
public void setValue(String s) throws SQLException;
public void translate(int x, int y);
public void translate(double x, double y);
} |
The X coordinate of the point.
The Y coordinate of the point.
Creates a new PGpoint object. The x and y fields are undefined.
Parameters.
The X coordinate.
The Y coordinate.
Parameters.
The definition of this point in Red Hat Database's syntax.
Creates a new PGpoint object that is exactly the same as this one.
Compare the current PGpoint object with another PGpoint object.
Parameters.
The object to compare with.
Returns. Returns true if the two points are identical; false otherwise.
Returns the definition of the PGpoint in Red Hat Database point syntax.
Returns. The PGpoint in the syntax expected by Red Hat Database.
Moves the point to the supplied coordinates.
Parameters.
The new X coordinate.
The new Y coordinate.
Moves the point to the supplied coordinates.
Parameters.
The new X coordinate.
The new Y coordinate.
Moves the point to the supplied coordinates. This method is the same as move(int, int).
Parameters.
The new X coordinate.
The new Y coordinate.
Moves the point to the coordinate defined by the supplied Point.
Parameters.
The point to move to.
This method sets the X and Y coordinates of this PGpoint. The Red Hat Database point syntax must be used.
Parameters.
The definition of this point in the Red Hat Database point syntax.
Throws: SQLException on conversion failure.
Translates the point by the given amount. The new position of the PGpoint p at (x, y) will be (x + dx, y + dy).
Parameters.
The integer amount to move on the X axis.
The integer amount to move on the Y axis.
Translates the point by the given amount. The new position of the PGpoint p at (x, y) will be (x + dx, y + dy).
Parameters.
The double amount to move on the X axis.
The double amount to move on the Y axis.
This implements the lseg data type. lseg represents a finite line or line segment; the line does not extend beyond its two endpoints.
package org.postgresql.geometric;
public class PGlseg extends PGobject
implements Serializable, Cloneable {
// Variables
public PGpoint[] point;
// Constructors
public PGlseg();
public PGlseg(double x1, double y1, double x2, double y2);
public PGlseg(PGpoint p1, PGpoint p2);
public PGlseg(String s) throws SQLException;
// Methods
public Object clone();
public boolean equals(Object obj);
public String getValue();
public void setValue(String s) throws SQLException;
} |
The two end-points of the line segment.
Creates a new PGlseg object. The two points are undefined.
Creates a new PGlseg object with endpoints (x1, y1) and (x2, y2).
Parameters.
The X coordinate for the first end-point.
The Y coordinate for the first end-point.
The X coordinate for the second end-point.
The Y coordinate for the second end-point.
Creates a new PGlseg object with endpoints p1 and p2.
Parameters.
The first end-point.
The second end-point.
Creates a new PGlseg object using the Red Hat Database syntax for the lseg data type.
Parameters.
The definition of the circle in Red Hat Database syntax.
Throws: SQLException on conversion failure.
Creates a new PGlseg object that is exactly the same as this one.
Compares the current PGlseg with another PGlseg object.
Parameters.
Object to compare with.
Returns. Returns true if the two PGlseg objects are identical; false otherwise.
Returns the definition of the PGlseg in Red Hat Database lseg syntax.
Returns. The PGlseg in the syntax expected by Red Hat Database.
This method sets the two end-points. The Red Hat Database lseg definition syntax must be used.
Parameters.
The definition of the line segment in Red Hat Database syntax.
Throws: SQLException on conversion failure.
This implements an infinite line which is defined by two points. The line data type exists in the backend but is currently unimplemented. This class is included for completeness.
package org.postgresql.geometric;
public class PGline extends PGobject
implements Serializable, Cloneable {
// Variables
public PGpoint[] point;
// Constructors
public PGline();
public PGline(double x1, double y1, double x2, double y2);
public PGline(PGpoint p1, PGpoint p2);
public PGline(String s) throws SQLException;
// Methods
public Object clone();
public boolean equals(Object obj);
public String getValue();
public void setValue(String s) throws SQLException;
} |
The two end-points that define the line.
Creates a new PGline object. The two points are undefined.
Creates a new PGlseg object with endpoints (x1, y1) and (x2, y2).
Parameters.
The X coordinate for the first point.
The Y coordinate for the first point.
The X coordinate for the second point.
The Y coordinate for the second point.
Creates a new PGlseg object with the points p1 and p2.
Parameters.
The first point.
The second point.
Creates a new PGlseg object using the Red Hat Database syntax for the lseg data type.
Parameters.
The definition of the circle in Red Hat Database syntax.
Throws: SQLException on conversion failure.
Creates a new PGline object that is exactly the same as this one.
Compares the current PGline with another PGline object.
Parameters.
Object to compare with.
Returns. Returns true if the two PGline objects are identical; false otherwise.
Returns the definition of the PGline in Red Hat Database line syntax.
Returns. The PGline in the syntax expected by Red Hat Database.
This method sets the two end-points of this PGline. The Red Hat Database line definition syntax must be used.
Parameters.
The definition of the line segment in Red Hat Database syntax.
Throws: SQLException on conversion failure.
The PGbox class represents Red Hat Database's box data type. A box is represented by a pair of points, the opposite corners of the box.
package org.postgresql.geometric;
public class PGbox extends PGobject
implements Serializable, Cloneable {
// Variables
public PGpoint[] point;
// Constructors
public PGbox(double x1, double y1, double x2, double y2);
// Methods
public Object clone();
public boolean equals(Object obj);
public String getValue();
public void setValue(String value) throws SQLException;
} |
The two corner points of the box.
Creates a new PGbox object. The values of the two corner points are undefined.
Creates a new PGbox object whose corner points are (x1, y1) and (x2, y2).
Parameters.
The X coordinate for the first point.
The Y coordinate for the first point.
The X coordinate for the second point.
The Y coordinate for the second point.
Creates a new PGbox object whose corner points are p1 and p2.
Parameters.
The first point.
The second point.
Creates a new PGbox object whose definition is given in the Red Hat Database syntax.
Parameters.
The definition of the box in Red Hat Database syntax.
Throws: SQLException if the definition is invalid.
Creates a new PGbox object that is exactly the same as this one.
Compares the current PGbox with another PGbox object.
Parameters.
Object to compare with.
Returns. Returns true if the two PGbox objects are identical; false otherwise.
Returns the definition of the PGbox in Red Hat Database syntax.
Returns. The PGbox in the syntax expected by Red Hat Database.
This method sets the position of the two corner points of this PGbox object. The Red Hat Database line definition syntax must be used.
Parameters.
The PGbox definition in Red Hat Database syntax.
Throws: SQLException thrown if value is invalid.
The PGbox class represents Red Hat Database's polygon data type.
package org.postgresql.geometric;
public class PGpolygon extends PGobject
implements Serializable, Cloneable {
// Variables
public PGpoint[] points;
// Constructors
public PGpolygon();
public PGpolygon(PGpoint points[]);
public PGpolygon(String s) throws SQLException;
// Methods
public Object clone();
public boolean equals(Object obj);
public String getValue();
public void setValue(String s) throws SQLException;
} |
The points defining the polygon.
Creates a new PGpolygon. The points making up the polygon are undefined.
Creates a PGpolygon using an array of PGpooints.
Parameters.
The points defining the polygon.
Creates a new PGpolygon using the Red Hat Database syntax for the polygon data type.
Parameters.
Definition of the polygon in Red Hat Database polygon syntax.
Throws: SQLException on conversion failure.
Creates a new PGpolygon object that is exactly the same as this one.
Compares the current PGpolygon object with another PGpolygon object
Parameters.
The object to compare with.
Returns. True if the two polygons are identical.
Returns the definition of the PGpolygon in Red Hat Database syntax.
Returns. The PGpolygon definition in the syntax expected by Red Hat Database.
Sets the points that make up this PGpolygon. The Red Hat Database polygon syntax must be used.
Parameters.
Definition of the polygon in Red Hat Database polygon syntax.
Throws: SQLException on conversion failure.
PGcircle represents Red Hat Database's circle data type. A circle consists of a center point and a radius.
package org.postgresql.geometric;
public class PGcircle extends PGobject implements
Serializable, Cloneable {
// Variables
public PGpoint center;
public double radius;
// Constructors
public PGcircle();
public PGcircle(double x, double y, double r);
public PGcircle(PGpoint c, double r);
public PGcircle(String s) throws SQLException;
// Methods
public Object clone();
public boolean equals(Object obj);
public String getValue();
public void setValue(String s) throws SQLException;
}
|
The center point of the circle.
The radius of the circle.
Creates a new PGcircle object. The center and radius are undefined.
Creates a new PGcircle object with center (x, y) and radius r.
Parameters.
The X coordinate of the center.
The Y coordinate of the center.
The radius.
Creates a new PGcircle object with center c and radius r.
Parameters.
PGpoint describing the circle's center.
The radius.
Creates a new PGcircle using the Red Hat Database syntax for the circle data type.
Parameters.
Definition of the circle in Red Hat Database circle syntax.
Creates a new PGcircle object that is exactly the same as this one.
Compares the current PGcircle object with another PGcircle object.
Parameters.
Object to compare with.
Returns. True if the two PGcircle objects are identical.
Returns the definition of the PGcircle in Red Hat Database syntax.
Returns. The PGcircle definition in the syntax expected by Red Hat Database.
Sets the center and radius of this PGcircle. The Red Hat Database circle syntax must be used.
Parameters.
The definition of the circle in Red Hat Database circle syntax.
Throws: SQLException on conversion failure.
PGpath implements a path, a line with multiple segments. The path may or may not be closed.
package org.postgresql.geometric;
public class PGpath extends PGobject implements
Serializable, Cloneable {
// Variables
public boolean open;
public PGpoint[] points;
// Constructors
public PGpath();
public PGpath(PGpoint points[], boolean open);
public PGpath(String s) throws SQLException;
// Methods
public Object clone();
public void closePath();
public boolean equals(Object obj);
public String getValue();
public boolean isClosed();
public boolean isOpen();
public void openPath();
public void setValue(String s) throws SQLException;
}
|
True if the path is open, false if closed.
The points that define a path.
Creates a new PGpath object. The number of points and their values are undefined.
Creates a new PGpath object based on the given points.
Parameters.
The PGpoints that define the path.
True if the path is open, false if closed.
Creates a new PGpath object using the Red Hat Database syntax for the path data type.
Parameters.
Definition of the path in PostgreSQL's syntax.
Throws:
SQLException on conversion failure.
Creates a new PGpath object that is exactly the same as this one.
Marks the path as closed.
Compares the current PGpath with another PGpath object.
Parameters.
Object to compare with.
Returns. True if the two paths are identical.
Returns the definition of the PGpath in Red Hat Database path syntax.
Returns true if the path is closed.
Returns true if the path is open.
Marks the path as open.
Sets the points of this PGpath. The Red Hat Database path syntax must be used.
Parameters.
Definition of the path in Red Hat Database syntax.
Throws:
SQLException on conversion failure.