|
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Object | +--com.isomorphic.datasource.DSRequest
Server-side representation of a DataSource request initiated by a client-side DataBoundComponent or programmatically by custom client-side JavaScript.
When databound components need to load or persist data, they make Ajax background requests to the server. Those requests are decoded into DSRequest Java objects by SmartClient's server-side Java libraries.
You obtain a DSRequest obtain by either:
RPCManager
and calling
com.isomorphic.rpc.RPCManager.getRequests
.
If you are integrating SmartClient with a pre-existing Java data store, you can call various
getters on the DSRequest, such as
getCriteria()
, to retrieve request parameters that
you can then use with your pre-existing data store. For example, when working with an ORM
(Object Relational Mapping) system, a typical way of processing an "update" DSRequest is to:
DataTools.setProperties()
to
apply new properties to the object, based on the Java Beans naming convention
Built-in connectors: SQL, Hibernate
The SmartClient Server can also automatically process DSRequests from DataSources with
serverType="sql" or serverType="hibernate". In this case, you can call
execute()
to cause the default behavior to occur, which will return a
DSResponse
populated with data supplied by Hibernate or SQL.
By modifying the DSRequest before you call execute() and by modifying the DSResponse you receive, you can combine SmartClient's built-in SQL support with custom processing.
For example, if you have a SQL table of records that are specific to each user, and there is a column containing the user's id, you could use setFieldValue() to ensure the DSRequest always contains the user's id. This would ensure that fetch, add, update and remove operations are always restricted to the user's own data.
RPCManager
,
DSResponse
Field Summary | |
static long |
ENDROW_UNSET
If endRow is set to this constant, then there is no set bound for the number of records the server should return for the current request. |
Constructor Summary | |
DSRequest(java.lang.String dataSourceName,
java.lang.String operationType)
Creates an empty DSRequest bound to the named datasource with the specified operationType. |
Method Summary | |
void |
addToTemplateContext(java.lang.String name,
java.lang.Object value)
If you're using the Velocity-based SQL Templating, you can make additional Java objects available to the the template context by calling this method. |
DSResponse |
execute()
Executes this DSRequest and returns a DSResponse. |
java.util.Map |
getCriteria()
This is a convenience method - it is useful for when you know there can only be one set of criteria. |
java.util.List |
getCriteriaSets()
Returns the criteria for this operation as a set of key-value pairs where the keys are field names and the values are field values. |
DataSource |
getDataSource()
Returns an instance of class DataSource for this DSRequest. |
java.lang.String |
getDataSourceName()
Returns the dataSourceName for this DSRequest. |
long |
getEndRow()
Returns the index of the last requested record. |
java.lang.Object |
getFieldValue(java.lang.Object fieldName)
Returns the value for a particular fieldName. |
java.util.Map |
getOldValues()
This is a convenience method - it is useful for when you know there can only be one set of oldValues. |
java.util.List |
getOldValueSets()
For an "update" or "remove" operation, returns the complete original record as it was delivered to the client, as a set of key-value pairs where the keys are field names and the values are field values. |
java.lang.String |
getOperationId()
Optional operationId passed by the client. |
java.lang.String |
getOperationType()
Returns the type of this DataSource operation. |
java.util.List |
getSortByFields()
The sortBy specification is only valid for the fetch operation since it specifies the sort order for the returned data. |
long |
getStartRow()
When components that are capable or showing multiple records at once are bound to datasources with large datasets, it becomes important to only send those records that are currently visible in the component (or can become visible with a typical user action). |
ISCFileItem |
getUploadedFile(java.lang.String fieldName)
|
java.util.Map |
getValues()
This is a convenience method - it is useful for when you know there can only be one set of values. |
java.util.List |
getValueSets()
Returns the values for this operation as a set of key-value pairs where the keys are field names and the values are field values. |
boolean |
isPaged()
Returns true if the current request has is requestinga partial set of data using startRow/endRow parameters. |
void |
setCriteria(java.lang.Object criteria)
Sets the criteria for this DSRequest. |
void |
setEndRow(long endRow)
Sets the index of the last requested record. |
void |
setFieldValue(java.lang.Object fieldName,
java.lang.Object value)
Sets the value for a particular fieldName. |
void |
setOperationType(java.lang.String operationType)
Sets the operation type. |
void |
setStartRow(long startRow)
Sets the index of the first requested record. |
void |
setValues(java.lang.Object values)
Sets the values for this DSRequest. |
ErrorReport |
validate()
Performs validation on the values in this DSRequest. |
Field Detail |
public static final long ENDROW_UNSET
getEndRow()
Constructor Detail |
public DSRequest(java.lang.String dataSourceName, java.lang.String operationType)
dataSourceName
- name of the datasource for this requestoperationType
- operationType for this requestMethod Detail |
public java.lang.String getOperationType()
public void setOperationType(java.lang.String operationType)
operationType
- the operation type - see above for valid values.public java.lang.String getOperationId()
The operationId is a means for client-side DataBound Components to request variants
of the basic DataSource operations that the server may support, such as normal
fetch
operations vs fetch
operations that use a single
parameter and do full-text search. See the Client Reference for DSRequest.operationId
for more information.
public java.util.Map getCriteria()
If you call this method on a DSRequest that contains multiple criteria sets, a warning is logged and the first criteria set in the list is returned by this method.
See also getCriteriaSets() for a description on the meaning of criteria by operationType.
getCriteria()
public java.util.List getCriteriaSets()
If the operationType is "fetch", then the criteria specifies the search criteria.
If the operationType is "remove" or "update" then the criteria the primary key/value pairs for the record to be updated or deleted. This set of fields is derived directly from the field specification in the dataSource for this operation - all fields marked as {primaryKey: true} are considered primary keys and their field names and values will be sent as part of the criteria in this case.
Note: this signature returns a List of criteria sets (Maps). This is the generic case and the recommended API because it captures interactions like removing multiple records. If there is only one set of criteria, then you will get a List with one Map.
getCriteria()
,
getValueSets()
public void setCriteria(java.lang.Object criteria)
criteria
- Map or List of Maps: the criteria to use for this DSRequestgetCriteriaSets()
public ISCFileItem getUploadedFile(java.lang.String fieldName) throws java.lang.Exception
fileName
- Form field of type 'binary'.public java.util.Map getValues()
If you call this method on a DSRequest that contains multiple value sets, a warning is logged and the first value set in the list is returned by this method.
As a convenience, this method returns the criteria for if this DSRequest is of type fetch or remove.
See also getValueSets() for a description on the meaning of criteria by operationType.
getValueSets()
,
getCriteriaSets()
public java.util.List getValueSets()
If the operationType is "add" then the values are interpreted as a complete record to add. Note that a complete record at this stage may be missing primary keys that are expected to be auto-generated by the persistence layer.
If the operationType is "update", then the values represent the new values for the records matching the criteria specified on this request.
As a convenience, this method returns the criteria for if this DSRequest is of type fetch or remove.
Note: this signagure returns a List of value sets (Maps). This is the generic case and the recommended API because it captures interactions like adding multiple records at once. If there is only one set of values, then you will get a List with one Map.
getValues()
,
getCriteriaSets()
public void setValues(java.lang.Object values)
values
- Map or List of Maps - the values to use for this DSRequestpublic java.util.Map getOldValues()
If you call this method on a DSRequest that contains multiple value sets, a warning is logged and the first value set in the list is returned by this method.
See also getOldValueSets() for a description on the meaning of criteria by operationType.
public java.util.List getOldValueSets()
The server can compare the oldValues
to the most recent stored values in
order to detect that the user was looking at stale values when the user submitted
changes (NOTE: this means of detecting concurrent edit is sometimes called "long
transactions").
Note that client logic must be written to pass
Note: this signagure returns a List of value sets (Maps). This is the generic case and
the recommended API because it captures interactions like updating multiple records at
once. If there is only one set of values, then you will get a List with one Map.oldValues
. SmartClient
DataBound Components do so automatically, but manually submitted DSRequests may not.
getOldValues()
public java.util.List getSortByFields()
This method signature is the generic method that returns all fields for which a sort has been requested. If the list contains more than one entry, then that means the data should be sorted by the first field in the list, then within that first sort data should be sorted by the next field in the list and so on. So the second sortBy field can only affect data that has the same value for the first sortBy field.
The returned value is a List of Strings that are the names of the fields to sort by. If
the String is prefixed by a -
then that specifies descending order.
Otherwise it's a request for an ascending sort on that field.
A concrete example of when a sortBy is sent by an ISC databound component: Let's say you have a ListGrid that has a partially loaded dataset (the dataset is too large to be on the client at once, so you're only showing, say, the first 100 rows). If you now click on one of the columns to sort by that column, the ListGrid will send a DSRequest to the server with a sortBy fieldName of the field that was clicked on. Since not all data is present on the client, the grid can't do the sort client-side (and still continue to display the first 100 matches to the curent filter criteria).
public boolean isPaged()
getStartRow()
,
getEndRow()
,
ENDROW_UNSET
public long getStartRow()
When multi-record capable components make requests to the server for data, they send the startRow and endRow parameters to indicate the slice of data they need to show to the user right now.
You can use the isPaged() method on this request to check if you need to respect startRow/endRow for this request.
Note that startRow and endRow are zero-based, so startRow: 0, endRow: 1 is a request for the first two records.
getEndRow()
,
isPaged()
public void setStartRow(long startRow)
Note that startRow and endRow are zero-based, so startRow: 0, endRow: 1 is a request for the first two records.
startRow
- the index of the first requested record (using zero-based numbering)public long getEndRow()
If getEndRow() returns DSRequest.ENDROW_UNSET (a negative value), that signifies a request for all records matching the current criteria.
Note that startRow and endRow are zero-based, so startRow: 0, endRow: 1 is a request for the first two records.
getStartRow()
,
ENDROW_UNSET
public void setEndRow(long endRow)
Note that startRow and endRow are zero-based, so startRow: 0, endRow: 1 is a request for the first two records.
endRow
- the index of the last requested record (using zero-based numbering)public java.lang.Object getFieldValue(java.lang.Object fieldName)
This is a convenience method. For any given operation, a particular fieldName will usually appear in either the valueSet or criteria.
fieldName
- the fieldName whose value you want to look uppublic void setFieldValue(java.lang.Object fieldName, java.lang.Object value)
This is a convenience method. For any given operation, a particular fieldName will usually appear in either the valueSet or criteria.
fieldName
- the fieldName whose value you want to setvalue
- the value to set for the field (added to valueSet if it exists, otherwise to
criteria)public java.lang.String getDataSourceName()
public DataSource getDataSource() throws java.lang.Exception
DataSource
,
getDataSourceName()
public ErrorReport validate() throws java.lang.Exception
If validation is successful for all fields, this method returns null. Otherwise it returns an ErrorReport for the first record that encountered a validation error.
ErrorReport
,
ErrorMessage
public DSResponse execute() throws java.lang.Exception
public void addToTemplateContext(java.lang.String name, java.lang.Object value)
name
- the name of the new object as it should appear in the Velocity namespacevalue
- arbitrary Java object
|
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |