com.sssw.rt.util
Interface AgiRowCursor

All Known Implementing Classes:

AgcData, AgoData, com.sssw.rt.util.AgoRowCursor, AgoVectorRowCursor

public interface AgiRowCursor

This interface is the public API for data navigation. It provides methods to navigate and manipulate a single row of a dataset at a time.

Navigation does not guarantee that all data is pre-fetched from the server; consequently, navigation operations can fail. For SilverStream-provided objects that implement AgiRowCursor, however, changes to the data, are guaranteed to be buffered until a call to AgiRowSetManager.updateRows(). For this reason, data change operations cannot fail and do not throw exceptions.

Third-party controls that implement this interface can be data bound using the AgoBindingManager class.

Field Summary

static String	BANDNAME This distinguished property contains the name of the band in hierarchical AgiRowCursors retrieved from views.
static String	ORDINAL This distinguished property contains the row number of the current row in the currently retrieved set of rows

Method Summary

void	addAgiRowCursorListener(AgiRowCursorListener rcl) Add an event listener to this row cursor
boolean	allowsChildren() Check whether the current row allows children.
void	appendChild() Append a new row as the last child of the current row.
AgiRowCursor	copy() Make an identical copy of this AgiRowCursor.
void	delete() Marks a record as deleted in the client's image of the data.
Object	getProperty(int colnum) Get the value of the property at the specified column index of the current row.
Object	getProperty(String name) Get the value of the named property of the current row.
int	getPropertyCount() Get the number of properties supported by the current row.
int	getPropertyIndex(String name) Get the index of the named property.
String	getPropertyName(int colnum) Get the name of the property at the specified index
AgiRowSetEventProducer	getRowSetEventProducer() Get a reference to this cursor's associated AgiRowSetEventProducer
boolean	gotoChild() Navigate to the first child of the current row.
boolean	gotoFirst() Navigate to the first peer of the current row.
boolean	gotoLast() Navigate to the last peer of the current row.
boolean	gotoNext() Navigate to the next peer of the current row.
boolean	gotoParent() Navigate to the parent of the current row.
boolean	gotoPrevious() Navigate to the previous peer of the current row.
boolean	gotoRoot() Navigate to the top-most parent of the current row.
boolean	hasChildren() Check whether the current row has children.
void	insertAfter() Insert a new row immediately after the current row.
void	insertBefore() Insert a new row immediately before the current row.
void	makePrimaryVersion() If the current row is part of a versioning table, copy the data from the current row to the corresponding row in the source (primary) table.
void	removeAgiRowCursorListener(AgiRowCursorListener rcl) Remove an event listener from this row cursor
boolean	setProperty(int colnum, Object value) Set the value of the property at the specified index of the current row.
boolean	setProperty(String name, Object value) Set the value of the named property of the current row.

Field Detail

BANDNAME

public static final String BANDNAME

This distinguished property contains the name of the band in hierarchical AgiRowCursors retrieved from views. Use with AgiRowCursor.getProperty(String).

The BANDNAME property can be used for row cursors retrieved from multi-band views created using the SilverStream Designer. It allows the application to tell what kind of row the row cursor is pointing to. For example:

  String bn = (String) rc.getProperty(AgiRowCursor.BANDNAME);
 

This tells the application the name of the band to which the current row belongs. Views can have multiple sub-bands at the same level. When navigating using a row cursor, the rows from the first sub-band can flow uninterrupted into the rows of the second sub-band. That is, the row cursor could point to a row from one sub-band, and after a call to rc.gotoNext(), the row cursor might point to a row from another sub-band.

ORDINAL

public static final String ORDINAL

This distinguished property contains the row number of the current row in the currently retrieved set of rows

The ORDINAL property can be used for row cursors retrieved from multi-band views created using the SilverStream Designer. It allows the application to tell the ordinal number of the current row that cursor is pointing to. For example:

  Integer ord = (Integer)
  agcData1.getProperty(AgiRowCursor.ORDINAL);
 

This tells the application the ordinal number of the current row. That is, this is the first row, the second row, the 39th row, etc. This allows you, for example, to display "row 3 of 57", and the like.

Method Detail

gotoFirst

public boolean gotoFirst()
                  throws AgoSecurityException,
                         AgoTransientSystemException,
                         AgoUnrecoverableSystemException

Navigate to the first peer of the current row.

Returns:

true if successful. If false is returned, the cursor is unchanged.

Example:

 	boolean successful;
 	try
 	{
 		successful = rc.gotoFirst();
 	}
 	catch (AgoApiException e)
 	{
 		agDialog.displayError(e);
 	}
 

See Also:

AgoSecurityException, AgoTransientSystemException, AgoUnrecoverableSystemException

gotoLast

public boolean gotoLast()
                 throws AgoSecurityException,
                        AgoTransientSystemException,
                        AgoUnrecoverableSystemException

Navigate to the last peer of the current row.

Returns:

true if successful. If false is returned, the cursor is unchanged.

Example:

 	boolean successful;
 	try
 	{
 		successful = rc.gotoLast();
 	}
 	catch (AgoApiException e)
 	{
 		agDialog.displayError(e);
 	}
 

gotoNext

public boolean gotoNext()
                 throws AgoSecurityException,
                        AgoTransientSystemException,
                        AgoUnrecoverableSystemException

Navigate to the next peer of the current row.

Returns:

True if successful. False if the cursor is unchanged.

Example:

 	boolean successful;
 	try
 	{
 		successful = rc.gotoNext();
 	}
 	catch (AgoApiException e)
 	{
 		agDialog.displayError(e);
 	}
 

See Also:

AgoSecurityException, AgoTransientSystemException, AgoUnrecoverableSystemException

gotoPrevious

public boolean gotoPrevious()
                     throws AgoSecurityException,
                            AgoTransientSystemException,
                            AgoUnrecoverableSystemException

Navigate to the previous peer of the current row.

Returns:

true if successful. If not successful, false is returned, and the cursor is unchanged.

Example:

 	boolean successful;
 	try
 	{
 		successful = rc.gotoPrevious();
 	}
 	catch (AgoApiException e)
 	{
 		agDialog.displayError(e);
 	}
 

allowsChildren

public boolean allowsChildren()

Check whether the current row allows children. Use this method when working with a hierarchical row cursor, such as that returned by a hierarchial view.

Returns:

true if the current row can have children.

Usage:

A true return value does not necessarily indicate that the current row has any children, only that they are allowed.

See Also:

AgiRowCursor.appendChild(), AgiRowCursor.hasChildren()

hasChildren

public boolean hasChildren()

Check whether the current row has children.

Returns:

true if the current row has children.

Example:

 	if (rc.hasChildren())
 	{
 		// Do something with the child rows...
 	}
 

See Also:

AgiRowCursor.allowsChildren(), AgiRowCursor.appendChild()

gotoChild

public boolean gotoChild()
                  throws AgoSecurityException,
                         AgoTransientSystemException,
                         AgoUnrecoverableSystemException

Navigate to the first child of the current row.

Returns:

true if successful. If false is returned, the cursor is unchanged.

Example:

 	try
 	{
 		if (rc.gotoChild())
 		{
 			// Do something with the child row
 		}
 	}
 	catch (AgoException e)
 	{
 		// Handle the exception here
 	}

gotoParent

public boolean gotoParent()
                   throws AgoSecurityException,
                          AgoTransientSystemException,
                          AgoUnrecoverableSystemException

Navigate to the parent of the current row.

Returns:

true if successful. If false is returned, the cursor is unchanged.

Example:

 	try
 	{
 		if (!rc.gotoParent())
 		{
 			// No parent row...
 		}
 	}
 	catch (AgoException e)
 	{
 		// Handle the exception...
 	}
 

gotoRoot

public boolean gotoRoot()
                 throws AgoSecurityException,
                        AgoTransientSystemException,
                        AgoUnrecoverableSystemException

Navigate to the top-most parent of the current row.

Returns:

True if successful. If false is returned, the cursor is unchanged.

Example:

 	boolean successful;
 	try
 	{
 		successful = rc.gotoRoot();
 	}
 	catch (AgoApiException e)
 	{
 		agDialog.displayError(e);
 	}
 

getProperty

public Object getProperty(String name)

Get the value of the named property of the current row.

Parameters:

name - the name of the column to obtain

Example:

  String name = (String) rc.getProperty("customername");
 

See Also:

AgiRowCursor.BANDNAME, AgiRowCursor.ORDINAL, AgiRowCursor.setProperty(String, Object)

setProperty

public boolean setProperty(String name,
                           Object value)

Set the value of the named property of the current row.

Parameters:

name - the name of the property whose value is set

value - the value to which the property is set. For a list of mappings between Java and SQL Object types, see Java and SQL Object Conversions in on-line help under General Reference.

Returns:

true if the modification succeeded.

Example:

 	rc.setProperty("Customers.CustomerName", "Bob Smith");
 

getProperty

public Object getProperty(int colnum)

Get the value of the property at the specified column index of the current row.

Parameters:

colnum - the index of the column to obtain. The column indices are zero-based.

Example:

  String lastName;
  lastName = (String) rc.getProperty(3);
 

See Also:

AgiRowCursor.setProperty(int, Object)

setProperty

public boolean setProperty(int colnum,
                           Object value)

Set the value of the property at the specified index of the current row.

Parameters:

colnum - the index of the property whose value is set

value - the value to which the property is set. For a list of mappings between Java and SQL Object types, see Java and SQL Object Conversions in on-line help under General Reference.

Returns:

true if the modification succeeded.

Example:

 	rc.setProperty(3, "Bob Smith");
 

getPropertyCount

public int getPropertyCount()

Get the number of properties supported by the current row.

Returns:

the number of properties (columns) provided by the current row.

Example:

  int numberOfProperties;
  numberOfProperties = rc.getPropertyCount();
 

getPropertyName

public String getPropertyName(int colnum)

Get the name of the property at the specified index

Parameters:

colnum - specifies the index of the column. Property indices are zero-based.

Returns:

The name

Example:

  String propertyName;
  propertyName = rc.getPropertyName(3);
 

See Also:

AgiRowCursor.setProperty(int, Object), AgiRowCursor.getProperty(int), AgiRowCursor.getPropertyIndex(String)

getPropertyIndex

public int getPropertyIndex(String name)

Get the index of the named property.

Parameters:

name - specifies the name of the column. Property indices are zero-based.

Returns:

the index.

Example:

  int index;
  index = rc.getPropertyIndex();
 

See Also:

AgiRowCursor.setProperty(int, Object), AgiRowCursor.getProperty(int), AgiRowCursor.getPropertyName(int)

delete

public void delete()

Marks a record as deleted in the client's image of the data.

Usage:

After this operation, the current row is automatically changed to the next or previous record. The cursor no longer navigates to a record marked as deleted. The record is not actually deleted from the database until the AgiRowSetManager.updateRows() method is called.

Example:

  rc.delete();
 

insertBefore

public void insertBefore()

Insert a new row immediately before the current row. After this operation, the new row is current.

Example:

  rc.insertBefore();
 

insertAfter

public void insertAfter()

Insert a new row immediately after the current row. After this operation, the new row is current.

Example:

  rc.insertAfter();
 

appendChild

public void appendChild()

Append a new row as the last child of the current row. After this operation, the new row is current. Children can only be appended to records when AgiRowCursor.allowsChildren() is true.

makePrimaryVersion

public void makePrimaryVersion()

If the current row is part of a versioning table, copy the data from the current row to the corresponding row in the source (primary) table.

Usage:

Like other changes to data made through a SilverStream row cursor, this change is bufferred until a call to AgiRowSetManager.updateRows().

Example:

 	rc.makePrimaryVersion();
 

addAgiRowCursorListener

public void addAgiRowCursorListener(AgiRowCursorListener rcl)

Add an event listener to this row cursor

Parameters:

rcl - the event listener to add

Usage:

Use this method to provide an object to receive AgiRowCursorListener events. This is an alternative to coding directly on these events in the Programming Editor.

Example:

 	agcData1.addAgiRowCursorListener(myObject);
 

removeAgiRowCursorListener

public void removeAgiRowCursorListener(AgiRowCursorListener rcl)

Remove an event listener from this row cursor

Parameters:

rcl - the event listener to remove

Example:

 	agcData1.removeAgiRowCursorListener(myObject);
 

copy

public AgiRowCursor copy()

Make an identical copy of this AgiRowCursor.

Example:

The following code fragment illustrates how to make a copy of an AgiRowCursor.

  AgiRowCursor newRC;
  newRC = oldRC.copy();
 

getRowSetEventProducer

public AgiRowSetEventProducer getRowSetEventProducer()

Get a reference to this cursor's associated AgiRowSetEventProducer