SilverStream
Application Server 3.5

com.sssw.rt.util
Interface AgiRowSetManager

All Known Implementing Classes:
AgcChoice, AgcComboBox, AgcData, AgcJComboBox, AgcJList, AgcJTable, AgcJTree, AgcList, AgcTreeControl, AgcViewDownloadable, AgoData, AgpListBase, AgpViewPanel, AgaRowData

public interface AgiRowSetManager

This interface is the public API for manipulation of a set of rows.

It provides methods to populate, update, or refresh the contents of a dataset.


Method Summary
 void clearRows()
          Discard all cached rows and all changes, freeing any storage.
 boolean haveRowsChanged()
          Check if any modifications have been made to the data or the structure of the data since the last call to AgiRowSetManager.updateRows(), AgiRowSetManager.refreshRows(), or AgiRowSetManager.query(String, String).
 void query(String query)
          Run a new query or orderby clause, discarding all changes.
 void query(String query, String orderBy)
          Run a new query or orderby clause, discarding all changes.
 void refreshRows()
          Pull new data from the server, discarding all changes to the data.
 void updateRows()
          Writes changes to the data and the structure of the data back to the data source.
 

Method Detail

haveRowsChanged

public boolean haveRowsChanged()
Check if any modifications have been made to the data or the structure of the data since the last call to AgiRowSetManager.updateRows(), AgiRowSetManager.refreshRows(), or AgiRowSetManager.query(String, String).
Returns:
true if the data have changed
Usage:

This method reflects the state of all rows, not just the current row.

Example:
  boolean changed;
  changed = agcData1.haveRowsChanged();
 

updateRows

public void updateRows()
                throws AgoSecurityException,
                       AgoTransientSystemException,
                       AgoUnrecoverableSystemException,
                       AgoInvalidDataException,
                       AgoMissingDataException,
                       AgoDataConcurrencyException
Writes changes to the data and the structure of the data back to the data source.
Usage:

This method writes changes to all of the rows, not just the current row. For agData, the updateRows() method writes changes made to the current form or page and all contained subforms, subpages and data controls.

The changes are written as a single transaction if all data comes from the same database. If data comes from multiple databases, changes are written in one transaction per database. Within a single transaction, the changes are written in the order in which the were made by the user.

When you are programming a form or page that uses data from an SAP DSO, you must call updateRows() before executing the RFC. The updateRows() method passes any local data (from the form or page data) to the SAP DSO. Note that the form or page needs to be in a state where a call to updateRows() is meaningful. You can force this state, by calling insertAfter() on the pageLoaded or formActivated events, then you can call updateRows().

Example:
 	try
 	{
 		agData.updateRows();
 	}
 	catch (AgoApiException e)
 	{
 		agDialog.displayError(e);
 	}
 

refreshRows

public void refreshRows()
                 throws AgoSecurityException,
                        AgoTransientSystemException,
                        AgoUnrecoverableSystemException
Pull new data from the server, discarding all changes to the data. Note that this re-executes the most recent query, but with up-to-date data. That is, if you call query() to restrict the set of rows and then call refreshRows(), the same restriction applies. To get back to all rows, call query(null).
Example:
 	try
 	{
 		agData.refreshRows();
 	}
 	catch (AgoApiException e)
 	{
 		agDialog.displayError(e);
 	}
 

clearRows

public void clearRows()
               throws AgoSecurityException,
                      AgoTransientSystemException,
                      AgoUnrecoverableSystemException
Discard all cached rows and all changes, freeing any storage. Puts the AgiRowSetManager in a state in which it has no rows to navigate; a call to gotoFirst() will return false.
Example:
 	try
 	{
 		agcData1.clearRows();
 	}
 	catch (AgoApiException e)
 	{
 		agDialog.displayError(e);
 	}
 

query

public void query(String query,
                  String orderBy)
           throws AgoSecurityException,
                  AgoTransientSystemException,
                  AgoUnrecoverableSystemException
Run a new query or orderby clause, discarding all changes. Specifies a String that represents a SQL Where clause and a SQL Order By clause.
Parameters:
query - the Where condition(s)
orderBy - the Order by specification
Usage:

The query() method causes the control to get all new contents, so any buffered changes are discarded.

The tablename.columnname syntax must be used in the query string.

Any fields contained in the query String must already be referenced by the control's original dataset.

SilverStream automatically appends the Where keyword, so it should not be included in the query String.

If a Where Clause is specified at design time (using the Property Inspector) and also programmatically by calling query(), the query() Where Clause is ANDed to the Where Clause property to create a single clause.

Note that SilverStream does not perform any SQL syntax checking on the query clause. Incorrect SQL syntax generates a runtime error or returns no data. Since some database management systems are case-sensitive, the table and field references should exactly match the names used in the database.

Any of the valid relational operators may be used including: =, <>, <, >, <=, >=, In, Not In, Between, and Not Between in the Where Clause.

If an Order By clause is specified at design time and also programmatically by calling query(), the query() Order By clause replaces the design-time Order By clause.

With ComboBox or List controls, query() can only be called if the Load Choices property is set to From Table.

Passing null for the query removes any previous programmatically supplied Where clause and requeries for all records. Passing null for the Order By clause retrieves the records in the order of the design-time Order By clause, or, if there is none, in an order determined by the database.

The query() method includes a special keyword constant that is used with the SAP Enterprise Data Connector. The constant is "EXECUTE". It causes the RFCObject to execute the associated SAP RFC. For example,

AgcData.query("EXECUTE")
executes the RFC and refreshes the data in the AgcData object.

If you have multiple AgxDatas bound to the same RFC, you just need to call query("EXECUTE") once and all of the AgxData controls associated with the RFC are updated. It does not matter which client DSO issues this call, but it should be the first in the list, for example:

agcData1.query ("EXECUTE"); // Executes the RFC
 agcData2.query (null);           // Refreshes the rows for this DSO
 agcData3.query (null);           // Refreshes the rows for this DSO
 
Example:

The following example restricts the results to employees whose employee id is greater than 0. It returns the result set in ascending employee name order. (Use "desc" to specify a descending order.)

 	query("employees.empid > 0", "employee.emp_name asc");
 

An example specifying only the Order By clause:

 	query(null, "employee.emp-name asc");
 

query

public void query(String query)
           throws AgoSecurityException,
                  AgoTransientSystemException,
                  AgoUnrecoverableSystemException
Run a new query or orderby clause, discarding all changes. Specifies a String that represents a SQL Where clause used to update the contents of a control.
Parameters:
query - the Where condition(s)
Usage:

The query() method causes the control to get all new contents, so any buffered changes are discarded.

The tablename.columnname syntax must be used in the query string.

Any fields contained in the query String must already be referenced by the control's original dataset.

SilverStream automatically appends the Where keyword, so it should not be included in the query String.

If a Where Clause is specified at design time (using the Property Inspector) and also programmatically by calling query(), the query() Where Clause is ANDed to the Where Clause property to create a single clause.

Note that SilverStream does not perform any SQL syntax checking on the query clause. Incorrect SQL syntax generates a runtime error or returns no data. Since some database management systems are case-sensitive, the table and field references should exactly match the names used in the database.

Any of the valid relational operators may be used including: =, <>, <, >, <=, >=, In, Not In, Between, and Not Between in the Where Clause.

With ComboBox or List controls, query() may be called only if the Load Choices property is set to From Table.

Passing null for the query removes any previous programmatically supplied Where clause and requeries for all records.

The query() method includes a special keyword constant that is used with the SAP Enterprise Data Connector. The constant is "EXECUTE". It causes the RFCObject to execute the associated SAP RFC. For example,

AgcData.query("EXECUTE")
executes the RFC and refreshes the data in the AgcData object. If you have multiple AgxDatas bound to the same RFC, you just need to call query("EXECUTE") once and all of the AgxData controls associated with the RFC are updated. It does not matter which client DSO issues this call, but it should be the first in the list, for example:
agcData1.query ("EXECUTE"); // Executes the RFC
 agcData2.query (null);           // Refreshes the rows for this DSO
 agcData3.query (null);           // Refreshes the rows for this DSO
 
Example:

The following example restricts the results to employees whose employee id is greater than 0:

 	agData.query("employees.empid > 0");
 

SilverStream
Application Server 3.5