/*
* 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.
*
*/
// DbTagValueIterator2
// ************ package ******************************************************
package KFM.DB;
// ************ imports ******************************************************
import KFM.Exceptions.*;
import KFM.GUI.TagCreator.*;
import KFM.Exceptions.IteratorException;
import java.sql.SQLException;
/****************************************************************************
*
* DbTagValueIterator2 is a TagValueIterator (q.v.) for a KfmTransientDBTable2 (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: changed access modifier of kfmTable from private to protected
* Changes: introduced method hasMoreElements()
* Changes: introduced the concept of a 'range' of visible (i.e. accessible) rows
* Changes: changed the class from an abstract to a concrete one.
*/
public class DbTagValueIterator2 implements TagValueIteratorInterface
{
//
// Constants
//
static final private int cursorUnset = -2;
//
// Variables
//
protected KfmTransientDBTable2 kfmTable = null;
// HACK: die �bergabe der ID sollte ausschliesslich durch KfmTransientDBTable2 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 TransientDBTable2
*
* @param names List of column names.
* @param database a valid database
*/
public DbTagValueIterator2 (String[] theColNames, KFM_Database theDatabase)
// throws SQLException
{
kfmTable = new KfmTransientDBTable2(theColNames, theDatabase);
kfmTable.connectIterator(this);
}
/**
* This version supports a shared iterator, that is more iterators
* has use the same TransientDBTable2
*
* @param aTable the shared transient table
*/
protected DbTagValueIterator2 (KfmTransientDBTable2 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 DbTagValueIterator2 ()
{
}
/**
* This version supports a shared iterator, that is more iterators
* has use the same TransientDBTable2.
*
* @param aTable the shared transient table
* @param theColNames List of column names.
* @param theDatabase a valid database
*/
protected void connectIterator (KfmTransientDBTable2 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.
*/
public void loadTable (String sql)
throws KFM_SQLException
{
//kfmTable = new KfmTransientDBTable2();
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.
*/
public void appendTable (String sql)
throws KFM_SQLException
{
//kfmTable = new KfmTransientDBTable2();
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("DbTagValueIterator2::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("DbTagValueIterator2::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;
}
/**
* @see KfmTransientDbTable2.isColName
*/
public boolean isColName(String name)
{
return kfmTable.isColName(name);
}
/** 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 KfmTransientDBTable2.
*
* Note by ThH: This method was added by HS on 1999-06-24.
* He did not know that DbTagValueIterator2 should use *names* (Strings) instead of position (ints)
* to access the columns, so he just copied the signature of `TransientDBTable2.sort�.
*
* @see KfmTransientDBTable2#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>Modified by KS on 2001-01-12: The range is taken into account.</P>
*
* <P>Added by ThH on 2000-05-18.</P>
*
* @return number of rows which are currently loaded.
*/
public int size()
{
int tSize = kfmTable.size();
if ((mRangeFrom <= -1) && (mRangeTo <= -1)) // no range was specified
return tSize;
if (mRangeTo <= -1) {
// A lower, but no upper range was specified.
// Subtract the lower range from tSize, but return at least 0.
return java.lang.Math.max(0, tSize - mRangeFrom);
}
if (mRangeFrom <= -1) {
// An upper, but no lower range was specified.
// Return either tSize or mRangeTo+1, whichever is less.
return java.lang.Math.min(tSize, mRangeTo+1);
}
// Both a lower and an upper range were specified.
// Take either tSize or mRangeTo+1, whichever is less, and
// subtract the lower range. Return at least 0.
return java.lang.Math.max(0, java.lang.Math.min(tSize, mRangeTo+1) - mRangeFrom);
}
/**
* Return the <B>human-readable text</B> that the `FormContentCreator� displays
* next to the checkbox, button, whatever.
* This method is part of the interface `TagValueIteratorInterface�.
*
* <P> Note: Misnamed, has nothing to do with HTML tags. </P>
* <P> Note again: It was formerly declared as 'abstract', but has a default implementation. </P>
*
* <P> Original documentation: The returned string will be used by the OptionTagCreator
* as the value of the html parameter TEXT. </P>
*
*@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.
*/
public String getTagText(String language)
{
return "";
}
/**
* 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.
*
* <P> Note: It was formerly declared as 'abstract', but has a default implementation. </P>
*/
public String getTagValue()
{
return "";
}
}