/*
* This software and supporting documentation were developed by
*
* Siemens Corporate Technology
* Competence Center Knowledge Management and Business Transformation
* D-81730 Munich, Germany
*
* Authors (representing a really great team ;-) )
* Stefan B. Augustin, Thorbj�rn Hansen, Manfred Langen
*
* This software is Open Source under GNU General Public License (GPL).
* Read the text of this license in LICENSE.TXT
* or look at www.opensource.org/licenses/
*
* Once more we emphasize, that:
* THIS SOFTWARE IS MADE AVAILABLE, AS IS, WITHOUT ANY WARRANTY
* REGARDING THE SOFTWARE, ITS PERFORMANCE OR
* FITNESS FOR ANY PARTICULAR USE, FREEDOM FROM ANY COMPUTER DISEASES OR
* ITS CONFORMITY TO ANY SPECIFICATION. THE ENTIRE RISK AS TO QUALITY AND
* PERFORMANCE OF THE SOFTWARE IS WITH THE USER.
*
*/
// DbTagValueIterator
// ************ package ******************************************************
package KFM.DB;
// ************ imports ******************************************************
import KFM.Exceptions.*;
import KFM.GUI.TagCreator.*;
import KFM.Exceptions.IteratorException;
import java.sql.SQLException;
/****************************************************************************
*
* DbTagValueIterator is a TagValueIterator (q.v.) for a KfmTransientDBTable (q.v.).
*
* This code was originally based on `MarketSegments�.
*
*
* Changes GUS: now implements directly TagValueIteratorInterface because
* it didn't need anything of class TagValueIterator
* Changes S: changed access modifier of kfmTable from private to protected
* Changes S: introduced method hasMoreElements()
* Changes S: introduced the concept of a 'range' of visible (i.e. accessible) rows
*/
abstract public class DbTagValueIterator implements TagValueIteratorInterface
{
//
// Constants
//
static final private int cursorUnset = -2;
//
// Variables
//
protected KfmTransientDBTable kfmTable = null;
// HACK: die �bergabe der ID sollte ausschliesslich durch KfmTransientDBTable erfolgen
// k�nnen. Dann sollte DbTagVI eine inner class davon werden oder
// ins gleiche package wandern.
public String mID;
/**
* Implements the built-in iterator/cursor.
*
* It is initialized to a value that will cause an error if the iterator is used without calling reset first.
*/
protected int cursor = cursorUnset;
/**
* The beginning of a visibility range (-1 if not relevant).
*
* @see #setRange()
*/
protected int mRangeFrom = -1;
/**
* The end of a visibility range (-1 if not relevant).
*
* @see #setRange()
*/
protected int mRangeTo = -1;
//
// Methods
//
/**
* This version supports a single iterator, that is every iterator
* has its own TransientDBTable
*
* @param names List of column names.
* @param database a valid database
*/
public DbTagValueIterator (String[] theColNames, KFM_Database theDatabase)
// throws SQLException
{
kfmTable = new KfmTransientDBTable(theColNames, theDatabase);
kfmTable.connectIterator(this);
}
/**
* This version supports a shared iterator, that is more iterators
* has use the same TransientDBTable
*
* @param aTable the shared transient table
*/
protected DbTagValueIterator (KfmTransientDBTable aTable)
{
this();
connectIterator(aTable);
}
/**
* This version prepares a shared iterator in a view.
* The subclass is responsible for calling method connectIterator().
*
* @see #connectIterator()
*
* @param names List of column names.
* @param database a valid database
*/
protected DbTagValueIterator ()
{
}
/**
* This version supports a shared iterator, that is more iterators
* has use the same TransientDBTable.
*
* @param aTable the shared transient table
* @param theColNames List of column names.
* @param theDatabase a valid database
*/
protected void connectIterator (KfmTransientDBTable aTable)
{
if (null != kfmTable)
kfmTable.disconnectIterator(mID);
kfmTable = aTable;
// connect to the table (e.g. for invalidation notifying)
kfmTable.connectIterator(this);
}
protected void finalize ()
throws Throwable
{
kfmTable.disconnectIterator(mID);
super.finalize();
}
/**
* Invalidates this iterator.
*
* Note: You must call `reset' to use this iterator again
*/
public synchronized void invalidate()
{
cursor = cursorUnset;
}
/**
* (Re-)execute with a different SQL statement but the same column names and database.
* It is typically used in a single view for getting a new subset of this view.
*
* @param sql Eine g�ltige SQL-Anweisung.
*/
protected void loadTable (String sql)
{
//kfmTable = new KfmTransientDBTable();
kfmTable.loadTable(sql);
}
/**
* (Re-)execute (and append the result set) with a different SQL statement but the same column names and database.
* It is typically used in a single view for getting a new subset of this view.
*
* @param sql Eine g�ltige SQL-Anweisung.
*/
protected void appendTable (String sql)
{
//kfmTable = new KfmTransientDBTable();
kfmTable.appendTable(sql);
}
/**
* Resets the unique built-in iterator.
* If a lower range was set (see setRange), reset() sets the cursor to the row before the lower range.<P>
*
* Note: You must call `next� once before you try to access the first value.
*/
public void reset()
{
if (mRangeFrom > 0)
cursor = mRangeFrom - 1;
else
cursor = -1;
}
/** Increments and tests the unique built-in iterator.
*
* <P>If an upper range was set (see setRange), next() returns false if the upper range is reached.</P>
*
* <P>Note: Call `reset� before f�rst use. If and only if it returns `true�, you can use the access methods like
* `getTagText� to access the stored information.</P>
*
* @return false if the iterator has already reached its end, true else.
*/
public boolean next()
{
if (cursor == cursorUnset) {
throw new IteratorException("DbTagValueIterator::next: You forgot reset().");
}
if (cursor+1 >= kfmTable.size())
return false;
if (mRangeTo >= 0) {
if (cursor+1 > mRangeTo)
return false;
}
++ cursor;
return true;
}
/** Tests if the built-in iterator has more elements.
*
* <P>If an upper range was set (see setRange), hasMoreElements() returns false if the upper range is
* reached.</P>
*
* <P>Note: This functionality is already achieved by method next(), but next() also
* iterates one row furter, which may not always be desired.</P>
*
* @return false if the iterator has already reached its end, true else.
*/
public boolean hasMoreElements()
{
if (cursor == cursorUnset) {
throw new IteratorException("DbTagValueIterator::next: You forgot reset().");
}
if (cursor+1 >= kfmTable.size())
return false;
if (mRangeTo >= 0) {
return (cursor+1 <= mRangeTo);
}
return true;
}
/** Set the range of visible (i.e. accessible) rows of the iterator.
*
* <P>This affects the working of reset() and next().
* Use a value of -1 (or any other negative value) to leave the range open to either end.</P>
*
* Examples:
* <UL>
* <LI> setRange(20,39) makes rows 20, 21, ..., 39 visible </LI>
* <LI> setRange(-1,19) makes rows 20, 21, ... invisible, </LI>
* <LI> setRange(12,-1) makes rows 0, 1, ..., 10, 11 invisible, </LI>
* <LI> setRange(-1,-1) makes everything visible (this is the default) </LI>
* <LI> setRange(10, 8) makes everything invisible </LI>
* </UL>
*
* </P>This method should always be called before reset().</P>
*
* @param from The first visible row (first row is counted 0) or -1 if irrelevant.
* @param to The last visible row (first row is counted 0) or -1 if irrelevant,
* it need not be <= than the size of the table.
*/
public void setRange (int from, int to)
{
mRangeFrom = from;
mRangeTo = to;
}
/** Return ID that the built in iterator points to, as String or null.
*
* @return A String or null: The ID that the built in iterator points to or null if the iterator was already at the end.
* Ist der Spaltenname oder die Zeile ung�ltig, dann wird null zur�ckgeliefert.
* Wenn der Wert in der DB SQLs NULL ist, dann wird `null� zur�ckgeliefert.
*
* @see getString
*/
public String get(String name)
{
return kfmTable.get(cursor, name);
}
/** Return ID that the built in iterator points to, always as String.
*
* @return Always return a String: the ID that the built in iterator points to or "" if the iterator was already at the end.
* Ist der Spaltenname oder die Zeile ung�ltig, dann wird "" zur�ckgeliefert.
* Wenn der Wert in der DB SQLs NULL ist, dann wird "" zur�ckgeliefert.
* @see get
*/
public String getString(String name)
{
return kfmTable.getString(cursor, name);
}
//Modification h99-06-24.
/**
* Sorts the table after a column. See also KfmTransientDBTable.
*
* Note by ThH: This method was added by HS on 1999-06-24.
* He did not know that DbTagValueIterator should use *names* (Strings) instead of position (ints)
* to access the columns, so he just copied the signature of `TransientDBTable.sort�.
*
* @see KfmTransientDBTable#sort(int, int, int)
* @param aColumnToSort column to be sorted. Starting with 1. E.g. if you want to access the first
* column use aColumnToSort=1.
* New: Now a name!
* @param aTypeToSort Type of the column which sould be sorted use <br>
* aTypeToSort=1 int <br>
* aTypeToSort=2 String <br>
* @param aSortDirection Chooses kind of sort operatio acsending or descending.<br>
* direction=1 aufw�rts (ascsending) <br>
* direction=2 abw�rts (descsending) <br>
*
*/
public synchronized boolean sort(
String aColumnToSort,
int aTypeToSort,
int aSortDirection)
{
return kfmTable.sort(aColumnToSort, aTypeToSort, aSortDirection );
}
//End Modification h99-06-24
/** Return number of rows which are currently loaded.
*
* <P>Added by ThH on 2000-05-18.</P>
*
* @return number of rows which are currently loaded.
*/
public int size()
{
return kfmTable.size();
}
/** Return the <B>human-readable text</B> that the `FormContentCreator� displays next to the checkbox, button, whatever.
*
* Note: Misnamed, has nothing to do with HTML tags.
*
* This method is part of the interface `TagValueIteratorInterface�.
*
* Original documentation: The returned string will be used by the OptionTagCreator as the value of the html
* parameter TEXT.
*
*@param language the preferred language.
*@return the "tag text" that the built in iterator points to in the preferred language or null if the
* iterator was already at the end.
*/
abstract public String getTagText(String language);
/** Return the <B>HTML parameter value</B> that the `FormContentCreator� inserts for the checkbox, button, whatever.
*
* This method is part of the interface OptionInterface. The returned string will be
* used by the OptionTagCreator as the value of the html parameter VALUE.
*/
abstract public String getTagValue();
}