A RowSet control is a special kind of Database control that is configured to perform CRUD (create, read, update, delete) operations on a specific database table or view using javax.sql.RowSet objects. All of the methods of a RowSet control operate directly on or return javax.sql.RowSet.
You should usually use the RowSet Control Wizard to create a RowSet control. A RowSet control must be configured in a precise way in order to function properly, with proper coordination between the database table metadata encoded in the control's JCX file and the control's methods.
To learn how to create a RowSet control using the RowSet Control Wizard, see How Do I: Create a RowSet Control to Access a Database?.
When a RowSet control is created via the RowSet Control Wizard, metadata describing the table or view on which the control operates is written to the control's JCX file as an XML Schema. Special annotations on the control's methods reference the schema and constrain the changes that are legal within the RowSet argument for each method.
The code below shows the body of a RowSet control generated for the simple CUSTOMER table used in the Database control sample found in SamplesApp/WebServices/database/CustomerDBClient.jws:
package customerrowset;
import java.sql.SQLException;
import javax.sql.RowSet;
import com.bea.control.DatabaseControl;
import com.bea.control.DatabaseFilter;
import com.bea.control.ControlExtension;
/**
* @jc:connection data-source-jndi-name="cgSampleDataSource"
* @common:schema file="#rowset-schemas" inline="true"
* @common:define name="rowset-schemas" value::
* <xsd:schema targetNamespace="java:///customerrowset" xmlns="java:///customerrowset" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:wld="http://www.bea.com/2002/10/weblogicdata" elementFormDefault="qualified" attributeFormDefault="unqualified">
* <xsd:element name="CUSTOMERRowSet" wld:DefaultNamespace="java:///customerrowset" wld:RowSet="true" wld:WriteTable="WEBLOGIC.CUSTOMER">
* <xsd:complexType>
* <xsd:choice maxOccurs="unbounded">
* <xsd:element name="CUSTOMERRow" wld:DatabaseProductName="PointBase">
* <xsd:complexType>
* <xsd:sequence>
* <xsd:element name="CUSTID" type="xsd:int" wld:JDBCType="INTEGER" minOccurs="0" wld:PrimaryKey="true" wld:ReadOnly="true" wld:TableName="WEBLOGIC.CUSTOMER" nillable="true" wld:EditMode="insert">
* </xsd:element>
* <xsd:element name="NAME" type="xsd:string" wld:JDBCType="VARCHAR" minOccurs="0" wld:TableName="WEBLOGIC.CUSTOMER" nillable="true">
* </xsd:element>
* <xsd:element name="ADDRESS" type="xsd:string" wld:JDBCType="VARCHAR" minOccurs="0" wld:TableName="WEBLOGIC.CUSTOMER" nillable="true">
* </xsd:element>
* ... remaining elements omitted ...
* </xsd:sequence>
* <xsd:anyAttribute namespace="http://www.bea.com/2002/10/weblogicdata" processContents="skip">
* </xsd:anyAttribute>
* </xsd:complexType>
* </xsd:element>
* </xsd:choice>
* </xsd:complexType>
* </xsd:element>
* </xsd:schema>::
*
*/
public interface CustomerRowSet extends ControlExtension, DatabaseControl
{
/** Disable default Java serialization */
public final static long serialVersionUID = 1L;
/**
* @jc:sql command-type="grid"
* rowset-name="CUSTOMERRowSet"
* max-rows="1000"
* statement::
* SELECT CUSTID,NAME,ADDRESS,CITY,STATE,ZIP,AREA_CODE,PHONE FROM WEBLOGIC.CUSTOMER {sql: filter.getWhereClause ()} {sql: filter.getOrderByClause ()}
* ::
*/
public RowSet getAllCustomer( DatabaseFilter filter )
throws SQLException;
/**
* @jc:sql command-type="detail"
* rowset-name="CUSTOMERRowSet"
* statement::
* SELECT CUSTID,NAME,ADDRESS,CITY,STATE,ZIP,AREA_CODE,PHONE FROM WEBLOGIC.CUSTOMER WHERE CUSTID = {x}
* ::
*/
public RowSet detailsCustomer( Integer x )
throws SQLException;
/**
* @jc:sql command-type="update"
* rowset-name="CUSTOMERRowSet"
*/
public RowSet updateCustomer( RowSet changedRs )
throws SQLException;
/**
* @jc:sql command-type="delete"
* rowset-name="CUSTOMERRowSet"
*/
public void deleteCustomer( RowSet oldRs )
throws SQLException;
/**
* @jc:sql command-type="templateRow"
* rowset-name="CUSTOMERRowSet"
*/
public RowSet detailsCustomerTemplate()
throws SQLException;
/**
* @jc:sql command-type="insert"
* rowset-name="CUSTOMERRowSet"
*/
public RowSet insertCustomer( RowSet changedRs )
throws SQLException;
/**
* @jc:sql command-type="insertedRow"
* rowset-name="CUSTOMERRowSet"
* statement::
* SELECT CUSTID,NAME,ADDRESS,CITY,STATE,ZIP,AREA_CODE,PHONE FROM WEBLOGIC.CUSTOMER WHERE CUSTID = ( Select Max ( CUSTID ) From WEBLOGIC.CUSTOMER)
* ::
*/
public RowSet getInserted()
throws SQLException;
}
When a RowSet control is created via the RowSet Control Wizard, the metadata for the database table or view on which the control will operate is recorded in the control's JCX file as an XML Schema. The @common:schema annotation declares a schema and references the schema definition. The @common:define annotation specifies the schema contents for a schema that is expressed inline in a JCX file. The schema defines the structure of the RowSet objects used in the control's methods.
The set of methods created by the RowSet Control Wizard depends on the choices you make in the wizard. In the preceding example, all operation on the database table were enabled while using the wizard.
Each RowSet control method is annotated with a @jc:sql annotation that specifies the rowset-name and command-type attributes. The rowset-name attribute references an element of the RowSet schema defined elsewhere in the file. The command-type attribute identifies the type of database operation that the method performs and also constrains the types of changes to a RowSet that each method will accept.
When creating a page flow using a RowSet control, the command-type attribute on the RowSet control's method is used by the page flow wizard to select the appropriate control method to invoke for each page flow action.
When each method of the RowSet control is invoked, the underlying Database control code uses the command-type attribute type on the method to constrain the types of changes that are allowed in the RowSet. For example, if a method with command-type="update" is invoked with a RowSet that contains row insertions, the control will throw an exception.