Overview  Package   Class  Tree  Deprecated  Index  Help 
 PREV CLASS   NEXT CLASS FRAMES    NO FRAMES    
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

com.knowgate.dataobjs
Class DBPersist

java.lang.Object
  |
  +--com.knowgate.dataobjs.DBPersist
Direct Known Subclasses:
Account, ACLDomain, ACLGroup, ACLUser, Address, Atom, Attachment, BankAccount, Bug, Category, CategoryLabel, Company, Contact, DistributionList, Duty, Fellow, FellowTitle, Image, Job, Keyword, Meeting, MetaAttribute, MicrositeDB, NewsMessage, Note, Oportunity, Order, PageSetDB, PhoneCall, Product, ProductAttribute, ProductKeyword, ProductLocation, Project, QueryByForm, Room, SalesMan, SalesObjectives, Shop, Subscription, Term, ToDo, WorkArea
public class DBPersist
extends java.lang.Object

Core class for persisting Java objects as registers in a RDMS.

Althought not an abstract class, DBPersist is mainly designed to be inherited by a child class implementing specific behavior for reading a writting a Java object from and to a relational database.

DBPersist mantains an internal collection of values each one mapped to a database field.

This mapping is done automatically by DBPersist reading the target table metadata definition and preparing the proper internal value set.

This object keeps the internal value set in memory as long as it is not garbage collected, but it does not mantaing any session information nor transaction management with the database. It is the programmer's responsability to pass an open database connection on each method call and to commit or rollback transaction involving the usage of a DBPersist object.

Version:
2.1

Field Summary
protected  java.util.HashMap AllVals
           
protected  java.lang.String sAuditCls
           
protected  java.lang.String sAuditUsr
           
protected  java.lang.String sTransactId
           
 
Constructor Summary
DBPersist(java.lang.String sTableName, java.lang.String sAuditClass)
           
 
Method Summary
 void clear()
          Clears internal values.
 boolean delete(JDCConnection oConn)
          Delete a register from database The deleted register will be the one matching this DBPersist primary key, as set at constructor or load() method.
 boolean exists(JDCConnection oConn)
          Find out whether or not a particular register exists at database
 java.lang.Object get(java.lang.String sKey)
          Get value for a field name
 java.util.Date getDate(java.lang.String sKey)
          Get value for a DATE field
 java.lang.String getDateFormated(java.lang.String sKey, java.lang.String sFormat)
          Get value for a DATE, DATETIME or TIMESTAMP field formated a String
 java.math.BigDecimal getDecimal(java.lang.String sKey)
          Get value for a DECIMAL or NUMERIC field
 float getFloat(java.lang.String sKey)
          Get value for a FLOAT or NUMBER([1..38],m) field
 int getInt(java.lang.String sKey)
          Get value for a INTEGER or NUMBER([1..11]) field
 java.lang.Integer getInteger(java.lang.String sKey)
          Get value for a INTEGER or NUMBER([1..11]) field
 java.util.HashMap getItemMap()
           
 java.util.Set getItems()
           
 short getShort(java.lang.String sKey)
          Get value for a SMALLINT field
 java.lang.String getString(java.lang.String sKey)
          Get value for a CHAR, VARCHAR or LONGVARCHAR field
 java.lang.String getStringNull(java.lang.String sKey, java.lang.String sDefault)
          Get value for a CHAR, VARCHAR or LONGVARCHAR field replacing null with a default value.
 DBTable getTable()
          Deprecated. Use getTable(JDCConnection) instead
 DBTable getTable(JDCConnection oConn)
          Get DBTable object witch holds this DBPersist registers.
 java.lang.String getTableName()
          Get base table name
 java.sql.Timestamp getTimestamp(java.lang.String sKey)
          Get value for a DATETIME or TIMESTAMP field
protected static java.lang.String getUIdFromName(JDCConnection oConn, java.lang.Integer iDomainId, java.lang.String sInstanceNm, java.lang.String sStoredProc)
          Internal method for being called by inherited classes Searches an object instance GUID from its unique name
 boolean isNull(java.lang.String sKey)
          Test is a readed field was null.
 java.util.Iterator iterator()
           
 boolean load(JDCConnection oConn, java.lang.Object[] PKVals)
          Load the internal value set from a register at a database table
 void parseXML(java.lang.String sXMLFilePath)
          Load an XML String into DBPersist internal collection.
 void put(java.lang.String sKey, java.math.BigDecimal oDecVal)
          Set value at internal collection
 void put(java.lang.String sKey, byte[] aBytes)
          Set reference to a byte array for a long field Use this method only for binding LONGVARBINARY or BLOB fields
 void put(java.lang.String sKey, char[] aChars)
          Set reference to a character array for a long field Use this method only for binding LONGVARCHAR or CLOB fields
 void put(java.lang.String sKey, java.util.Date dtVal)
          Set value at internal collection
 void put(java.lang.String sKey, double dVal)
          Set value at internal collection
 void put(java.lang.String sKey, java.io.File oFile)
          Set reference to a binary file for a long field
 void put(java.lang.String sKey, float fVal)
          Set value at internal collection
 void put(java.lang.String sKey, int iVal)
          Set value at internal collection
 void put(java.lang.String sKey, java.lang.Object oObj)
          Set value at internal collection
 void put(java.lang.String sKey, short iVal)
          Set value at internal collection
 void put(java.lang.String sKey, java.lang.String sVal)
          Set value at internal collection
 void put(java.lang.String sKey, java.lang.String sData, int iSQLType)
          Set value at internal collection
 void putAll(java.util.Properties oPropsCollection)
          Load values from a Properties object
 void remove(java.lang.String sKey)
          Remove a value from internal collection
 void replace(java.lang.String sKey, float fVal)
          Replace a value from internal collection
 void replace(java.lang.String sKey, int iVal)
          Replace a value from internal collection
 void replace(java.lang.String sKey, java.lang.Object oObj)
          Replace a value from internal collection
 void replace(java.lang.String sKey, short iVal)
          Replace a value from internal collection
 void setAuditTransact(java.lang.String sAuditTransact)
          Set transaction id for automatic operation auditing.
 void setAuditUser(java.lang.String sAuditUser)
          Set user id for automatic operation auditing.
 boolean store(JDCConnection oConn)
          Store a register at database representing this instance of DBPersist Insertions and updates : The store method automatically manages register insertions and updates.
 java.lang.String toXML()
          Get an XML dump for the DBPersist values.
 java.lang.String toXML(java.lang.String sIdent)
          Get an XML dump for the DBPersist values.
 java.lang.String toXML(java.lang.String sIdent, java.lang.String sDelim)
          Get an XML dump for the DBPersist values
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

AllVals

protected java.util.HashMap AllVals

sAuditCls

protected java.lang.String sAuditCls

sAuditUsr

protected java.lang.String sAuditUsr

sTransactId

protected java.lang.String sTransactId
Constructor Detail

DBPersist

public DBPersist(java.lang.String sTableName,
                 java.lang.String sAuditClass)
          throws java.lang.IllegalStateException
Parameters:
sAuditClass - Name of child Java class inheriting from DBPersist.
Method Detail

setAuditUser

public void setAuditUser(java.lang.String sAuditUser)
Set user id for automatic operation auditing.

setAuditTransact

public void setAuditTransact(java.lang.String sAuditTransact)
Set transaction id for automatic operation auditing.

clear

public void clear()

Clears internal values.

No register is deleted at the database.

get

public java.lang.Object get(java.lang.String sKey)

Get value for a field name

Parameters:
sKey - FieldName
Returns:
Field value. If field is null or DBPersist has not been loaded, or no field with given name exists at table, get() returns null.

getDecimal

public java.math.BigDecimal getDecimal(java.lang.String sKey)
                                throws java.lang.ClassCastException,
                                       java.lang.NumberFormatException

Get value for a DECIMAL or NUMERIC field

Parameters:
sKey - Field Name
Returns:
Field value or null.
Throws:
java.lang.ClassCastException
java.lang.NumberFormatException

getString

public java.lang.String getString(java.lang.String sKey)
                           throws java.lang.NullPointerException

Get value for a CHAR, VARCHAR or LONGVARCHAR field

Parameters:
sKey - Field Name
Returns:
Field value or null.
Throws:
java.lang.NullPointerException - if field is null or no field with such name was found at internal value collection.

getStringNull

public java.lang.String getStringNull(java.lang.String sKey,
                                      java.lang.String sDefault)

Get value for a CHAR, VARCHAR or LONGVARCHAR field replacing null with a default value.

Parameters:
sKey - Field Name
sDefault - Value to be returned if field is null. sDefault may itself be null, provinding a null safe version of getString() method.
Returns:
Field value or default value.

getShort

public short getShort(java.lang.String sKey)
               throws java.lang.NullPointerException

Get value for a SMALLINT field

Parameters:
sKey - Field Name
Returns:
Field value.
Throws:
java.lang.NullPointerException - if field is null or no field with such name was found at internal value collection.

getFloat

public float getFloat(java.lang.String sKey)
               throws java.lang.NullPointerException

Get value for a FLOAT or NUMBER([1..38],m) field

Parameters:
sKey - Field Name
Returns:
Field value.
Throws:
java.lang.NullPointerException - if field is null or no field with such name was found at internal value collection.

getInt

public int getInt(java.lang.String sKey)
           throws java.lang.NullPointerException

Get value for a INTEGER or NUMBER([1..11]) field

Parameters:
sKey - Field Name
Returns:
Field value.
Throws:
java.lang.NullPointerException - if field is null or no field with such name was found at internal value collection.

getInteger

public java.lang.Integer getInteger(java.lang.String sKey)

Get value for a INTEGER or NUMBER([1..11]) field

Parameters:
sKey - Field Name
Returns:
Field value or null.

getDate

public java.util.Date getDate(java.lang.String sKey)

Get value for a DATE field

Parameters:
sKey - Field Name
Returns:
Field value or null.

getDateFormated

public java.lang.String getDateFormated(java.lang.String sKey,
                                        java.lang.String sFormat)

Get value for a DATE, DATETIME or TIMESTAMP field formated a String

Parameters:
sKey - Field Name
sFormat - DateFormat
Returns:
Formated date or null.
See Also:
SimpleDateFormat

getTimestamp

public java.sql.Timestamp getTimestamp(java.lang.String sKey)

Get value for a DATETIME or TIMESTAMP field

Parameters:
sKey - Field Name
Returns:
Field value or null.

getItems

public java.util.Set getItems()
Returns:
Field Names Set

getItemMap

public java.util.HashMap getItemMap()
Returns:
Values Map

iterator

public java.util.Iterator iterator()
Returns:
Iterator for values stored in-memory at this DBPersist.

getTableName

public java.lang.String getTableName()
Get base table name

Returns:
Name of base table for this DBPersist

getTable

public DBTable getTable()
Deprecated. Use getTable(JDCConnection) instead

Returns:
DBTable object where data is stored or null if the table does not exist at the database.

getTable

public DBTable getTable(JDCConnection oConn)
                 throws java.sql.SQLException,
                        java.lang.IllegalStateException
Get DBTable object witch holds this DBPersist registers.

Parameters:
oConn - JDBC Database Connection
Returns:
DBTable object where data is stored or null if the table does not exist at the database.
Throws:
java.lang.IllegalStateException - DBPersist uses the internal static table map from DBBind. The internal DBBind table map is loaded upon first call to a DBBind constructor. Thus, if a DBPersist object is instantiated before instantiating any DBBind object, the internal table map will not be preloaded and an IllegalStateException will be raised.
java.sql.SQLException
Since:
2.0

isNull

public boolean isNull(java.lang.String sKey)
Test is a readed field was null.

Parameters:
sKey - Field Name
Returns:
true if readed field was null or if no field with given name was found at internal collection.

load

public boolean load(JDCConnection oConn,
                    java.lang.Object[] PKVals)
             throws java.sql.SQLException

Load the internal value set from a register at a database table

Parameters:
oConn - Database Connection
PKVals - Primary key values in order of appearance
Returns:
true if a register was found, false if no register was found with such primary key.
Throws:
java.sql.SQLException

put

public void put(java.lang.String sKey,
                java.lang.String sVal)

Set value at internal collection

Parameters:
sKey - Field Name
sVal - Field Value

put

public void put(java.lang.String sKey,
                java.lang.Object oObj)

Set value at internal collection

Parameters:
sKey - Field Name
oObj - Field Value

put

public void put(java.lang.String sKey,
                int iVal)

Set value at internal collection

Parameters:
sKey - Field Name
iVal - Field Value

put

public void put(java.lang.String sKey,
                short iVal)

Set value at internal collection

Parameters:
sKey - Field Name
iVal - Field Value

put

public void put(java.lang.String sKey,
                java.util.Date dtVal)

Set value at internal collection

Parameters:
sKey - Field Name
dtVal - Field Value

put

public void put(java.lang.String sKey,
                double dVal)

Set value at internal collection

Parameters:
sKey - Field Name
dVal - Field Value

put

public void put(java.lang.String sKey,
                java.math.BigDecimal oDecVal)

Set value at internal collection

Parameters:
sKey - Field Name
oDecVal - Field Value

put

public void put(java.lang.String sKey,
                float fVal)

Set value at internal collection

Parameters:
sKey - Field Name
fVal - Field Value

put

public void put(java.lang.String sKey,
                java.io.File oFile)
         throws java.io.FileNotFoundException

Set reference to a binary file for a long field

Parameters:
sKey - Field Name
oFile - File Object
Throws:
java.io.FileNotFoundException

put

public void put(java.lang.String sKey,
                byte[] aBytes)

Set reference to a byte array for a long field

Use this method only for binding LONGVARBINARY or BLOB fields

Parameters:
sKey - Field Name
aBytes - byte array

put

public void put(java.lang.String sKey,
                char[] aChars)

Set reference to a character array for a long field

Use this method only for binding LONGVARCHAR or CLOB fields

Parameters:
sKey - Field Name
aChars - char array

put

public void put(java.lang.String sKey,
                java.lang.String sData,
                int iSQLType)
         throws java.io.FileNotFoundException,
                java.lang.IllegalArgumentException

Set value at internal collection

Parameters:
sKey - Field Name
sData - Field Value as a String. If iSQLType is BLOB or LONGVARBINARY then sData is interpreted as a full file path uri.
iSQLType - SQL Type for field
Throws:
java.lang.IllegalArgumentException - If SQL Type is not recognized. Recognized types are { CHAR, VARCHAR, LONGVARCHAR, CLOB, INTEGER, SMALLINT, DATE, TIMESTAMP, DOUBLE, FLOAT, REAL, DECIMAL, NUMERIC, BLOB, LONGVARBINARY }
java.io.FileNotFoundException

putAll

public void putAll(java.util.Properties oPropsCollection)
            throws java.io.FileNotFoundException

Load values from a Properties object

java.io.FileNotFoundException

remove

public void remove(java.lang.String sKey)

Remove a value from internal collection

Parameters:
sKey - Field Name

replace

public void replace(java.lang.String sKey,
                    java.lang.Object oObj)

Replace a value from internal collection

Parameters:
sKey - Field Name
oObj - New Value

replace

public void replace(java.lang.String sKey,
                    int iVal)

Replace a value from internal collection

Parameters:
sKey - Field Name
iVal - New int value

replace

public void replace(java.lang.String sKey,
                    short iVal)

Replace a value from internal collection

Parameters:
sKey - Field Name
iVal - New short value

replace

public void replace(java.lang.String sKey,
                    float fVal)

Replace a value from internal collection

Parameters:
sKey - Field Name

store

public boolean store(JDCConnection oConn)
              throws java.sql.SQLException

Store a register at database representing this instance of DBPersist

Insertions and updates : The store method automatically manages register insertions and updates. If the stored object already exists at database then it is updated, if it does not exists then it is inserted. A primary key violation error is never thrown so ther is no need to call delete() method before re-writing an existing object.

NULL fields : All values not set calling put() methods for DBPersist will be assumed to be NULL. If a not nullable field is not set then an SQLException will be raised.
On storing an already existing object all values will we overwrited, so is a DBPersist is not fully loaded before storing it, values not set by calling put() methods that already were present at database will be lost.

Parameters:
oConn - Database Connection
Returns:
true is register was successfully stored, false if not.
Throws:
java.sql.SQLException

delete

public boolean delete(JDCConnection oConn)
               throws java.sql.SQLException

Delete a register from database

The deleted register will be the one matching this DBPersist primary key, as set at constructor or load() method.

Parameters:
oConn - Database connection
Returns:
true if register was successfully erased, false if not.
Throws:
java.sql.SQLException

exists

public boolean exists(JDCConnection oConn)
               throws java.sql.SQLException

Find out whether or not a particular register exists at database

Parameters:
oConn - database connection
Returns:
true if a register exists a DBPersist base table witch primary key coincides with the one set in memory for the DBPersist.
Throws:
java.sql.SQLException

toXML

public java.lang.String toXML(java.lang.String sIdent,
                              java.lang.String sDelim)
                       throws java.lang.IllegalStateException

Get an XML dump for the DBPersist values

Parameters:
sIdent - Number of blank spaces for left padding at every line.
sDelim - Line delimiter (usually "\n" or "\r\n")
Returns:
XML String
java.lang.IllegalStateException

toXML

public java.lang.String toXML(java.lang.String sIdent)

Get an XML dump for the DBPersist values.

Lines are delimited by a single Line Feed CHR(10) '\n' character.

Parameters:
sIdent - Number of blank spaces for left padding at every line.
Returns:
XML String

toXML

public java.lang.String toXML()

Get an XML dump for the DBPersist values.

No left padding is placed to the left of each line.

Lines are delimited by a single Line Feed CHR(10) '\n' character.

Returns:
XML String

parseXML

public void parseXML(java.lang.String sXMLFilePath)
              throws org.xml.sax.SAXException,
                     org.xml.sax.SAXNotRecognizedException,
                     org.xml.sax.SAXNotSupportedException,
                     org.xml.sax.SAXParseException,
                     java.io.IOException,
                     java.lang.ClassNotFoundException,
                     java.lang.IllegalAccessException,
                     java.lang.InstantiationException

Load an XML String into DBPersist internal collection.

Each tag ... found will be stored as a DBPersist value.

Example of input file:
<?xml version="1.0" encoding="ISO-8859-1"?>
<ACLUser>
  <gu_user>32f4f56fda343a5898c15a021203dd82</gu_user>
  <id_domain>1026</id_domain>
  <nm_user>The 7th Guest</nm_user>
  <tx_pwd>123456</tx_pwd>
  <tx_main_email>guest7@domain.com</tx_main_email>
  <tx_alt_email>admin@hipergate.com</tx_alt_email>
  <dt_last_updated>Fri, 29 Aug 2003 13:30:00 GMT+0130</dt_last_updated>
  <tx_comments><![CDATA[Sôme ñasti & ïnternational chars stuff]]></tx_comments>
</ACLUser>

Parameters:
sXMLFilePath - XML Path to XML file to parse
Throws:
org.xml.sax.SAXException
org.xml.sax.SAXNotRecognizedException
org.xml.sax.SAXNotSupportedException
org.xml.sax.SAXParseException
java.io.IOException
java.lang.ClassNotFoundException
java.lang.IllegalAccessException
java.lang.InstantiationException

getUIdFromName

protected static java.lang.String getUIdFromName(JDCConnection oConn,
                                                 java.lang.Integer iDomainId,
                                                 java.lang.String sInstanceNm,
                                                 java.lang.String sStoredProc)
                                          throws java.sql.SQLException

Internal method for being called by inherited classes

Searches an object instance GUID from its unique name

Parameters:
oConn - Database Connection
iDomainId - Domain Identifier
sInstanceNm - Instance Name
sStoredProc - Stored Procedure or PL/pgSQL Function Name
Returns:
Global Unique Identifier of instance been searched or null if no instance was found with such name.
Throws:
java.sql.SQLException
Overview  Package   Class  Tree  Deprecated  Index  Help 
 PREV CLASS   NEXT CLASS FRAMES    NO FRAMES    
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD