Field Detail

• ENDROW_UNSET

  public static final 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.

  See Also:

  DSRequest.getEndRow(), Constant Field Values

Constructor Detail

• DSRequest

  public DSRequest(java.lang.String dataSourceName,
                   java.lang.String operationType,
                   ValidationContext vc)

  Creates an empty DSRequest bound to the named datasource with the specified operationType. Depending on the operation you're performing you'll need to call some other setters on the returned instance before calling execute().

  Parameters:

  dataSourceName - name of the datasource for this request

  operationType - operationType for this request

• DSRequest

  public DSRequest(java.lang.String dataSourceName,
                   java.lang.String operationType,
                   RPCManager rpcManager)

  Creates an empty DSRequest bound to the named datasource with the specified operationType, and associated with the specified RPCManager. Depending on the operation you're performing you'll need to call some other setters on the returned instance before calling execute().

  Parameters:

  dataSourceName - name of the datasource for this request

  operationType - operationType for this request

  rpcManager - The RPCManager in use for this request

Method Detail

• getValidated

  public boolean getValidated()

  Returns true if this DSRequest has been validated. Ordinarily, this means the DSRequest's DSRequest.validate() method has been called and did not return any errors, but see also DSRequest.setValidated(boolean).

  Returns:

  true if this DSRequest has been validated

• setValidated

  public DSRequest setValidated(boolean newValue)

  Sets the validated state of this DSRequest. Ordinarily, a DSRequest is considered validated if its DSRequest.validate() method has been called and did not return any errors. You can use this API to directly set the validated state of a DSRequest.

  • If you set the validated state to true, and normal SmartClient/SmartGWT Server validation has not already been run, it will be skipped. You would do this if you had some reason for wanting to prevent ordinary validation
  • If you set the validated state to false, it is possible that normal SmartClient/SmartGWT Server validation will run again. For example, a DSRequest that is passed to a DMI goes through ordinary validation before the DMI is called. If the DMI calls setValidated(false) on the DSREquest then executes it, it will be validated again. This may be desirable if the DMI alters the DSRequest in some way/

  Returns:

  the DSRequest itself

• setPartOfTransaction

  public DSRequest setPartOfTransaction(boolean newValue)

  Controls how success or failure is reported for a request that executes alongside an automatically handled transaction.

  If you setPartOfTransaction(true) and the automatically handled transaction fails, the status for your DSRequest will be reported as STATUS_TRANSACTION_FAILED, which is an indication to the client that the DSRequest did nothing.

  Use this API if you have written custom Java code to handle a DSRequest, and:

  • you use @link{DataSource.getTransactionObject(DSRequest,String,String)} to obtain the current transaction and use hand-written JDBC, JPA or Hibernate code to run updates in the scope of the current transaction. Calling setPartOfTransaction(true) in this case reflects the fact that your updates will be automatically rolled back along with other updates in the automatically managed transaction.
  • you add use @link{RPCManager.registerCallback()} to be notified when the automatically managed transaction fails, and you manually rollback the consequences of your logic (for example, you remove a new file that had been added)

  You can also use this API to obtain correct behavior in the case of Exceptions from your own DMI code. For example, say you have this DMI method:

     public DSResponse myDMI(DSRequest req) {
         String str = req.getFieldValue("someField").toLowerCase();
         // Do something with str here
         return req.execute();
     }
   

  Here, by blindly calling a method without first checking for null, you introduce the possibility of this DMI crashing before the execute() call; the execute() call would have determined that this DSRequest should be part of the automatic transaction, meaning a failure of it would have rolled back the whole transaction. This early failure in DMI code leaves the DSRequest still separate from the transaction, so rollback would not happen.

  What we do in a case like this is check if the DSRequest would have joined the automatic transaction if the DMI had been bypassed: if it would, the DSRequest is considered to be part of the transaction. So in this case, the overall transaction would be rolled back in the event of a NullPointerException arising from the first line of the DMI method. That is correct and desirable failure behavior for this case and the majority of ordinary DMI usages on a built-in DataSource type, where the DMI is there to augment the built-in functionality, and dsRequest.execute() will ultimately be called.

  However, a DMI can do anything at all - there is no certainty that dsRequest.execute() will eventually be called. If the DMI described above did not make that call then the request would not have been part of the transaction regardless of success or failure, and our heuristic test - would the request have joined the transaction if the DMI had been bypassed? - would make the wrong decision. To prevent the possibility of this happening, you would either:

  • Call setPartOfTransaction(false) right at the top of your DMI method. This would handle transactional failure correctly without any further code to write
  • Put the entire DMI method inside a try-catch block and manually rollback the transaction if any Exception is thrown. You would only do this if you had a specific reason - it is easier to let the framework handle the transaction lifecycle. The method of committing or rolling back varies by DataSource type. For example, if it were a SQLDataSource, you would manually rollback like this:

             SQLTransaction.rollbackTransaction(dsRequest.getRPCManager());
             

  Returns:

  the DSRequest

  See Also:

  DataSource.getTransactionObject(DSRequest)

• getTextMatchStyle

  public java.lang.String getTextMatchStyle()

  Returns the textMatchStyle in force for this DSRequest, or null if none is set. See the client-side documentation for details of TextMatchStyle.

  Returns:

  The textMatchStyle in force for this DSRequest

• setTextMatchStyle

  public DSRequest setTextMatchStyle(java.lang.String textMatchStyle)

  Sets the textMatchStyle in force for this DSRequest. See the client-side documentation for details of TextMatchStyle.

  Returns:

  the DSRequest

• getRequestContext

  @Deprecated
  public RequestContext getRequestContext()

  Deprecated. Please use BaseRequest.getContext() instead.

• getOperationType

  public java.lang.String getOperationType()

  Returns the type of this DataSource operation.

  Returns:

  One of: "fetch", "add", "remove", "update", "validate" or "custom".

• setOperationType

  public DSRequest setOperationType(java.lang.String operationType)

  Sets the operation type. Valid values are one of: "fetch", "add", "remove", "update" or "custom".

  Parameters:

  operationType - the operation type - see above for valid values.

  Returns:

  the DSRequest

• getOperationId

  public java.lang.String getOperationId()

  Optional operationId passed by the client.

  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.

  Returns:

  the operationId

• setOperationId

  public DSRequest setOperationId(java.lang.String operationId)

  For server-initiated DSRequests, sets the operationId to control which operationBinding is used when fulfilling the requests.

  Parameters:

  operationId - the operationId to use

  Returns:

  the DSRequest

  See Also:

  DSRequest.getOperationId()

• getComponentId

  public java.lang.String getComponentId()

  Optional componentId passed by the client.

  For requests submitted by a SmartClient DataBoundComponent, this is the component ID.

  Returns:

  the componentId

• getCriteria

  public java.util.Map getCriteria()

  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. The meaning of criteria varies by operationType.

  If the operationType is "fetch", then the criteria specifies the search criteria.

  If the operationType is "remove" or "update" then the criteria are 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.

  The criteria returned from this method are in simple Java Collections form (as they are sent over the network). Use DSRequest.getAdvancedCriteria() to retrieve an AdvancedCriteria which provides simple APIs for manipulating criteria. The modified criteria can be applied to the DSRequest via DSRequest.setAdvancedCriteria(com.isomorphic.criteria.AdvancedCriteria).

  Returns:

  the criteria for this DSRequest

  See Also:

  DSRequest.getValues()

• getAdvancedCriteria

  public AdvancedCriteria getAdvancedCriteria()

  Returns the advanced criteria for this operation.

  If criteria were passed as simple Criteria this method will convert them to the more general AdvancedCriteria format by turning them into an AND Criterion containing one or more "startWith" or "contains" Criteria according to dsRequest.textMatchStyle.

  Note that AdvancedCriteria will only be able to be executed by the built-in server DataSources (JPA, Hibernate, SQL) in Power Edition and above.

  Returns:

  the advanced criteria for this DSRequest

• getIsAdvancedCriteria

  public boolean getIsAdvancedCriteria()

  Check if current criteria is advanced.

  AdvancedCriteria has "_constructor" parameter set to "AdvancedCriteria".

  Returns:

  flag showing if current criteria is advanced.

• setAdvancedCriteria

  public DSRequest setAdvancedCriteria(AdvancedCriteria advancedCriteria)

  Sets the criteria for this request to the provided AdvancedCriteria.

  Note: AdvancedCriteria will only be able to be executed by the built-in server DataSources (JPA, Hibernate, SQL) in Power Edition and above.

  Parameters:

  advancedCriteria - the criteria to use for this DSRequest

  Returns:

  the DSRequest

  See Also:

  DSRequest.getCriteria()

• getClientSuppliedCriteria

  public java.util.Map getClientSuppliedCriteria()

  Returns the criteria submitted by the client for this operation as a set of key-value pairs where the keys are field names and the values are field values. There may be differences between this set of values and the set returned by getCriteria(), because declarative security settings or custom server logic may have affected the latter. This method is provided so that your code can determine what the client actually sent, regardless of any server processing that has taken place.

  Returns:

  the criteria for this DSRequest

  See Also:

  DSRequest.getCriteria(), DSRequest.getClientSuppliedValues()

• getCriteriaSets

  public java.util.List getCriteriaSets()

  Returns the criteria in the request as a List, even if singular.

  Custom client-side code for submitting "update"s or "remove"s can pass multiple sets of criteria and values and oldValues as an alternative to using queuing (see the client-side API RPCManager.startQueue()). If you take this approach, calling getOldValueSets() is a convenience method for always retrieving sets of values as a List.

  Returns:

  List of criteria sets for this request

  See Also:

  DSRequest.getCriteria(), DSRequest.getValueSets()

• setCriteria

  public DSRequest setCriteria(java.lang.Object criteria)

  Sets the criteria for this DSRequest. You may pass either a Map or a List of Maps, but note that criteria has slightly different meanings for different operations, so be sure to read the API for getCriteriaSets() on this method for a description of what's required.

  The criteria passed in this method are in simple Java Collections form (as they are sent over the network), but you can get use DSRequest.setAdvancedCriteria(AdvancedCriteria) with AdvancedCriteria helper classes: AdvancedCriteria exists to assist in modifying the criteria.

  If AdvancedCriteria passed to this method DSRequest.setAdvancedCriteria(AdvancedCriteria) method will be used.

  Parameters:

  criteria - Map or List of Maps: the criteria to use for this DSRequest

  Returns:

  the DSRequest

  See Also:

  DSRequest.getCriteria()

• setCriteria

  public DSRequest setCriteria(java.lang.String fieldName,
                               java.lang.Object value)

  Sets the criteria for this DSRequest. This is a convenience method for the common case when you only have a single criterion.

  Parameters:

  fieldName - The field name

  value - The criterion value

  Returns:

  the DSRequest

  See Also:

  DSRequest.getCriteria()

• clearUploadedFiles

  public DSRequest clearUploadedFiles()

  Clears any uploaded files from this DSRequest. You may wish to do this in the case where you have a DMI method that has already dealt with uploaded files and you wish to prevent any downstream processing from attempting to do so again. Note that you should not actually need to manually clear uploaded files, if your DataSource is correctly configured.

  Returns:

  the DSRequest

• getUploadedFile

  public ISCFileItem getUploadedFile(java.lang.String fieldName)
                              throws java.lang.Exception

  Parameters:

  fieldName - Form field of type 'binary'.

  Returns:

  ISCFileItem containing uploaded file for specified field, or null if no file was uploaded for the specified field.

  Throws:

  java.lang.Exception

• getUploadedFiles

  public java.util.List getUploadedFiles()

  Returns:

  The list of ISCFileItems representing uploaded files on this DSRequest.

• getUploadedFileStream

  public java.io.InputStream getUploadedFileStream(java.lang.String fieldName)
                                            throws java.lang.Exception

  Parameters:

  fieldName - Form field of type 'binary'.

  Returns:

  InputStream representing uploaded file for specified field, or null if no file was uploaded for the specified field. Note that this InputStream is not necessarily the same one encapsulated by the corresponding ISCFileItem. Please see the ISCFileItem documentation for details

  Throws:

  java.lang.Exception

  See Also:

  ISCFileItem.getInputStream()

• getUploadedFileStreams

  public java.util.List getUploadedFileStreams()

  Returns:

  The list of InputStreams representing uploaded files on this DSRequest. Note that these InputStreams are not necessarily the same ones encapsulated by the ISCFileItem objects they pertain to. Please see the ISCFileItem documentation for details

  See Also:

  ISCFileItem.getInputStream()

• setIncludeBinaryFields

  public void setIncludeBinaryFields(boolean includeBinaryFields)

  Allows to override default binary fields behavior for server-initiated DSRequests that target SQLDataSource.

  By default binary fields are:

  • not selected if request came from the client and it is not a download request
  • not selected if it is an automatic cache sync request
  • selected if it is server-initiated request

  Parameters:

  includeBinaryFields - false to skip selecting binary fields

• getIncludeBinaryFields

  public boolean getIncludeBinaryFields()

  See Also:

  DSRequest.setIncludeBinaryFields(boolean)

• getValues

  public java.util.Map getValues()

  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. The meaning of values varies by operationType.

  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 if this DSRequest is of type fetch or remove.

  Returns:

  the values for this DSRequest

  See Also:

  DSRequest.getCriteria(), DSRequest.getOldValues(), DSRequest.getClientSuppliedValues()

• getClientSuppliedValues

  public java.util.Map getClientSuppliedValues()

  Returns the values that the client submitted for this operation as a set of key-value pairs where the keys are field names and the values are field values. There may be differences between this set of values and the set returned by getValues(), because declarative security settings or custom server logic may have affected the latter. This method is provided so that your code can determine what the client actually sent, regardless of any server processing that has taken place.

  As a convenience, this method returns the criteria that the client submitted if this DSRequest is of type fetch or remove.

  Returns:

  the values that the client actually sent for this DSRequest

  See Also:

  DSRequest.getCriteria(), DSRequest.getOldValues(), DSRequest.getClientSuppliedValues()

• getValueSets

  public java.util.List getValueSets()

  Returns the values in the request as a List, even if singular.

  Custom client-side code for submitting "update"s or "remove"s can pass multiple sets of criteria and values and oldValues as an alternative to using queuing (see the client-side API RPCManager.startQueue()). If you take this approach, calling getOldValueSets() is a convenience method for always retrieving sets of values as a List.

  Returns:

  List of value sets for this request.

  See Also:

  DSRequest.getValues(), DSRequest.getCriteriaSets()

• setValues

  public DSRequest setValues(java.lang.Object values)

  Sets the values for this DSRequest. You may pass either a Map or a List of Maps. The List type is typically used for a DataSource.OP_ADD operation with multiple records.

  Parameters:

  values - Map or List of Maps - the values to use for this DSRequest

  Returns:

  the DSRequest

• getOldValues

  public java.util.Map getOldValues()

  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.

  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 oldValues. SmartClient DataBound Components do so automatically, but manually submitted DSRequests may not.

  Returns:

  the oldValues for this DSRequest

  See Also:

  DSRequest.getValues()

• getOldValueSets

  public java.util.List getOldValueSets()

  Returns the oldValues in the request as a List, even if singular.

  Custom client-side code for submitting "update"s or "remove"s can pass multiple sets of criteria and values and oldValues as an alternative to using queuing (see the client-side API RPCManager.startQueue()). If you take this approach, calling getOldValueSets() is a convenience method for always retrieving sets of values as a List.

  Returns:

  List of value sets for this request.

  See Also:

  DSRequest.getOldValues()

• setOldValues

  public DSRequest setOldValues(java.util.Map oldValues)

  Sets the "old values" for this DSRequest (ie, the values as they were before the set of changes represented by this request).

  Parameters:

  oldValues - Map - the old values to use for this DSRequest

  Returns:

  the DSRequest

• getSortBy

  public java.lang.String getSortBy()

  This is a convenience method to be used when you know only a single sortBy field has been specified. Please see the getSortByFields() method on this class for a description of how ascending/descending sort is encoded.

  If you call this method on a DSRequest that has multiple sortBy fields specified, a warning will be logged and the first sortBy field will be returned.

  Returns:

  name of field to sort by

  See Also:

  DSRequest.getSortByFields()

• getSortByFields

  public java.util.List getSortByFields()

  The sortBy specification is only valid for the fetch operation since it specifies the sort order for the returned data.

  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 current filter criteria).

  Returns:

  set of fields to sort by

• setSortBy

  public DSRequest setSortBy(java.lang.Object sortBy)

  Sets the field or fields to sort by.

  Parameters:

  sortBy - String or List of Strings: field or list of fields to sort by. Note that a prefix of - can be used to specify descending order sort.

  Returns:

  the DSRequest

  See Also:

  DSRequest.getSortByFields()

• getGroupBy

  public java.util.List getGroupBy()

  List of fields to group results by.

  Valid only for an operation of type "fetch". See the Server Summaries overview in the client-side documentation for details and examples of usage.

  NOTE: this feature is supported only in Power Edition or above, and only when using the built-in SQL, JPA or Hibernate connectors.

  Returns:

  List with field names to group by, or null if no grouping is configured

  See Also:

  DSRequest.getSummaryFunctions(), DSRequest.getRawSummaryFunctions()

• setGroupBy

  public DSRequest setGroupBy(java.util.List groupBy)

  List of fields to group results by.

  Valid only for an operation of type "fetch". See the Server Summaries overview in the client-side documentation for details and examples of usage.

  NOTE: this feature is supported only in Power Edition or above, and only when using the built-in SQL, JPA or Hibernate connectors.

  Parameters:

  groupBy - List with field names to group by.

  See Also:

  DSRequest.setSummaryFunctions(java.util.Map), DSRequest.setRawSummaryFunctions(java.util.Map)

• setGroupBy

  public DSRequest setGroupBy(java.lang.String[] groupBy)

  For fetch operation group by fields can be set. In this case only fields that appear in this List and in dsRequest.summaryFunctions attribute will be fetched.

  Parameters:

  groupBy - String... with field names to group by.

  See Also:

  DSRequest.setSummaryFunctions(java.util.Map), DSRequest.setRawSummaryFunctions(java.util.Map)

• getSummaryFunctions

  public java.util.Map getSummaryFunctions()

  A mapping from field names to summary functions to be applied to each field.

  Valid only for an operation of type "fetch". See the Server Summaries overview in the client-side documentation for details and examples of usage.

  NOTE: this feature is supported only in Power Edition or above, and only when using the built-in SQL, JPA or Hibernate connectors.

  If you need to get all summary functions requested by the client, even if they are not framework built-ins, see DSRequest.getRawSummaryFunctions().

  Returns:

  Map<String,SummaryFunctionType> with field names as keys and summary functions as values.

  See Also:

  DSRequest.getGroupBy(), DSRequest.getRawSummaryFunctions()

• setSummaryFunctions

  public DSRequest setSummaryFunctions(java.util.Map summaryFunctions)

  A mapping from field names to summary functions to be applied to each field.

  Valid only for an operation of type "fetch". See the Server Summaries overview in the client-side documentation for details and examples of usage.

  NOTE: this feature is supported only in Power Edition or above, and only when using the built-in SQL, JPA or Hibernate connectors.

  Parameters:

  summaryFunctions - Map<String,SummaryFunctionType> with field names as keys and summary functions as values.

  See Also:

  DSRequest.setGroupBy(java.util.List), DSRequest.setRawSummaryFunctions(java.util.Map)

• getRawSummaryFunctions

  public java.util.Map getRawSummaryFunctions()

  Allows you to retrieve all summary functions requested by the client, even if they are not framework built-ins.

  DSRequest.getSummaryFunctions() will only return recognized, built-in summaryFunctions from the SummaryFunctionType enum, so getRawSummaryFunctions() is the only way to retrieve client-requested summary functions that are not built into the framework, so that you can perform custom aggregation. See the Server Summaries > Custom Aggregation example in the Showcase.

  NOTE: this feature is supported only in Power Edition or above, and only when using the built-in SQL, JPA or Hibernate connectors.

  Returns:

  Map<String,String> with field names as keys and summary functions as values.

  See Also:

  DSRequest.getGroupBy(), DSRequest.getSummaryFunctions()

• setRawSummaryFunctions

  public DSRequest setRawSummaryFunctions(java.util.Map rawSummaryFunctions)

  Allows you to set all summary functions requested by the client, even if they are not framework built-ins.

  DSRequest.getSummaryFunctions() will only return recognized, built-in summaryFunctions from the SummaryFunctionType enum, so getRawSummaryFunctions() is the only way to retrieve client-requested summary functions that are not built into the framework, so that you can perform custom aggregation. See the Server Summaries > Custom Aggregation example in the Showcase.

  NOTE: this feature is supported only in Power Edition or above, and only when using the built-in SQL, JPA or Hibernate connectors.

  Parameters:

  rawSummaryFunctions - Map<String,SummaryFunctionType> with field names as keys and summary functions as values.

  See Also:

  DSRequest.setGroupBy(java.util.List), DSRequest.setSummaryFunctions(java.util.Map)

• isPaged

  public boolean isPaged()

  Returns true if the current request has is requesting partial set of data using startRow/endRow parameters. Specifically, this method returns true if startRow is non-zero or endRow has a value other than DSRequest.ENDROW_UNSET.

  See Also:

  DSRequest.getStartRow(), DSRequest.getEndRow(), DSRequest.ENDROW_UNSET

• setBatchSize

  public DSRequest setBatchSize(long batchSize)

  If a batch size has been set it will be passed as a hint to the JDBC API using ResultSet.setFetchSize() and Statement.setFetchSize().

  The batch size will normally be based on DSRequest.endRow if that has been set and batchSize will then be set to the number of rows to be returned, so they are all fetched at once.

  For a request which does not have DSRequest.endRow set you can call DSRequest.setBatchSize(long) to try and influence the JDBC driver as a performance optimization. When using a Hibernate datasource criteria.setFetchSize will be called with this value.

  The batch size can also be controlled from a config property through server.properties, namely, 'sql.defaultFetchBatchSize'. By default this property is unset but once set it configures the batchSize for any "fetch" dsRequest that does not have an endRow.

  Parameters:

  batchSize - the size of the batch as a whole number.

  Returns:

  this DSRequest, allowing for chaining of method calls.

  See Also:

  DSRequest.setStartRow(long), DSRequest.setEndRow(long), DSRequest.ENDROW_UNSET

• getStartRow

  public 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).

  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, inclusive at the beginning and exclusive at the end (like substring), so startRow: 0, endRow: 1 is a request for the first record.

  Returns:

  index of the first requested record (using zero-based numbering)

  See Also:

  DSRequest.getEndRow(), DSRequest.isPaged()

• setStartRow

  public DSRequest setStartRow(long startRow)

  Sets the index of the first requested record.

  Note that startRow and endRow are zero-based, inclusive at the beginning and exclusive at the end (like substring), so startRow: 0, endRow: 1 is a request for the first record.

  Parameters:

  startRow - the index of the first requested record (using zero-based numbering)

  Returns:

  the DSRequest

• getEndRow

  public long getEndRow()

  Returns the index of the last requested record. See also the notes in getStartRow() for an example of when startRow/endRow are sent.

  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, inclusive at the beginning and exclusive at the end (like substring), so startRow: 0, endRow: 1 is a request for the first record.

  Returns:

  index of the last requested record (using zero-based numbering)

  See Also:

  DSRequest.getStartRow(), DSRequest.ENDROW_UNSET

• setEndRow

  public DSRequest setEndRow(long endRow)

  Sets the index of the last requested record.

  Note that startRow and endRow are zero-based, inclusive at the beginning and exclusive at the end (like substring), so startRow: 0, endRow: 1 is a request for the first record.

  Parameters:

  endRow - the index of the last requested record (using zero-based numbering)

  Returns:

  the DSRequest

• getProgressiveLoading

  public java.lang.Boolean getProgressiveLoading()

  Returns true if progressive loading is enabled, false if it is disabled for this particular request or null if this was not explicitly set, meaning that OperationBinding- and DataSource-level settings will be respected and automatically switching to loading data progressively if DataSource.progressiveLoadingThreshold is exceeded would also work as expected. Search for DataSource.progressiveLoading and DataSource.progressiveLoadingThreshold in SmartClient Reference for more details.

  Returns:

  Boolean true - progressive loading is explicitly enabled; false - progressive loading is explicitly disabled; null - default value to fall back to default behavior.

• setProgressiveLoading

  public DSRequest setProgressiveLoading(java.lang.Boolean progressiveLoading)

  Sets DataSource progressive loading mode for this particular request, overriding the OperationBinding- and DataSource-level settings. This setting overrides the DataSource.progressiveLoadingThreshold setting as well, meaning that if DSRequest.progressiveLoading is explicitly set to false SmartClient won't automatically switch to loading data progressively even if DataSource.progressiveLoadingThreshold is exceeded. Search for DataSource.progressiveLoading and DataSource.progressiveLoadingThreshold in SmartClient Reference for more details.

  Note that this setting applies only to fetch requests - it has no effect if specified on any other kind of request.

  Parameters:

  progressiveLoading - boolean true - progressive loading will be enabled; false - progressive loading will be disabled.

  Returns:

  the DSRequest

• getFieldValue

  public java.lang.Object getFieldValue(java.lang.Object fieldName)

  Returns the value for a particular fieldName if it exists in the valueSet, otherwise checks if the value exists in the criteria via getCriteriaValue(fieldName). This method treats the DSRequest as a single record. If the valueSet contains a value for the requested fieldName, it is returned. If not, the criteria is checked for the requested fieldName. If a value exists there, it is returned. Otherwise null is returned.

  This is a convenience method. For any given operation, a particular fieldName will usually appear in either the valueSet or criteria.

  Parameters:

  fieldName - the fieldName whose value you want to look up

  Returns:

  the value as found in valueSet or criteria

• getCriteriaValue

  public java.lang.Object getCriteriaValue(java.lang.Object fieldName)

  Returns the value provided in criteria for a particular fieldName.

  If AdvancedCriteria were passed, getCriteriaValue finds the first value provided for the fieldName anywhere in the AdvancedCriteria structure, by depth-first search.

  Parameters:

  fieldName - the fieldName whose criteria value you want to look up

  Returns:

  the value found in the criteria, or null if none found

• setCriteriaValue

  public java.lang.Object setCriteriaValue(java.lang.String fieldName,
                                           java.lang.Object value)

  Amends the request's criteria with the restriction that the indicated field equals the provided value. If the request criteria are AdvancedCriteria, setCriteriaValue will create a Criterion based on the current textMatchStyle of the DSRequest, and combine it with the existing AdvancedCriteria with an AndCriterion. Existing Criteria referencing the indicated fieldName are not modified.

  Otherwise, setCriteriaValue updates the existing criteria Map. Any existing criterion for the indicated fieldName is overwritten.

  Parameters:

  fieldName - indicated field of criterion

  value - required value the field must equal

  Returns:

  if existing criteria is simple, and if fieldName is already referenced in the criteria, then the overwritten criterion value; otherwise null

• setFieldValue

  public DSRequest setFieldValue(java.lang.Object fieldName,
                                 java.lang.Object value)

  Sets the value for a particular fieldName, in criteria or values according to the operation type.

  Generally, this method treats the criteria and values on the DSRequest as a single record: for "add" and "update" operations, the field value becomes part of the values to save. Otherwise ("fetch", "remove") the value is added to the criteria as though DSRequest.setCriteriaValue(String,Object) were called. For "update" operations, you set criteria values with the DSRequest.setCriteria(Object) or DSRequest.setCriteriaValue(String, Object) APIs. However, this distinction only applies for regular update-via-primaryKey, where allowMultiUpdate is not in force. Multi-update DSRequests must place the entire state of the update, both criteria and values, in the DSRequest values.

  Parameters:

  fieldName - the fieldName whose value you want to set

  value - the value to set for the field

• getDataSourceName

  public java.lang.String getDataSourceName()

  Returns the dataSourceName for this DSRequest. This will be the same name you passed as the dataSource attribute to the databound component issuing this request.

  Returns:

  name of the datasource for this DSRequest

• getDataSource

  public DataSource getDataSource()
                           throws java.lang.Exception

  Returns an instance of class DataSource for this DSRequest.

  Returns:

  dataSource instance for this DSRequest

  Throws:

  java.lang.Exception

  See Also:

  DataSource, DSRequest.getDataSourceName()

• getValidationMode

  public java.lang.String getValidationMode()

  Returns the validationMode associated with this DSRequest

  Returns:

  the validationMode associated with this DSRequest

• setValidationMode

  public DSRequest setValidationMode(java.lang.String validationMode)

  Sets the validationMode associated with this DSRequest

  Returns:

  the DSRequest

• getPendingAddFlag

  public boolean getPendingAddFlag()

  Returns the pendingAdd flag associated with this DSRequest

  Returns:

  the pendingAdd flag associated with this DSRequest

• setPendingAddFlag

  public DSRequest setPendingAddFlag(boolean pendingAdd)

  Sets the pendingAdd flag associated with this DSRequest

  Returns:

  the DSRequest

• validate

  public ErrorReport validate()
                       throws java.lang.Exception

  Performs validation on the values in this DSRequest. The values provided as part of this DSRequest are tested against the validators defined on a per-field basis in the dataSource (.ds.xml file).

  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.

  Returns:

  ErrorReport or null if there were no errors.

  Throws:

  java.lang.Exception

  See Also:

  ErrorReport, ErrorMessage

• getGenerateRelatedUpdates

  public java.lang.Boolean getGenerateRelatedUpdates()

  Should related updates be generated in DSResponse. Related updates issue additional requests to database thus reducing performance. By default (if value set to null) related updates will be generated only for "add" and "update" operations because related objects are loaded anyway and performance impact is minimal.

  Related updates for "remove" operation will not be generated by default (if value set to null). Related updates generation loads related objects from database while simple "remove" operation does not. Depending on database structure performance impact can be significant if value set to true.

  Returns:

  Boolean true - related updates will be generated; false - related updates will not be generated; null - related updates will be generated only for "add" and "update" operations, related updates will not be generated for "remove" operation.

• convertRelativeDates

  public void convertRelativeDates()

  Converts any relative dates found in this requests criteria into absolute dates relative to when this method is run.

  Note: This conversion happens internally and the criteria on this request will be modified.

  See Also:

  DataSource.convertRelativeDates(AdvancedCriteria, Date)

• call

  public DSResponse call()
                  throws java.lang.Exception

  Calls through to execute(). Be careful about resources used by the DSRequest - you may want to set setFreeOnExecute() to avoid having to wait for DSRequest garbage collection to clean up any consumed resources. On the other hand, if your logic depends on streaming data that would be terminated by freeing on execute, you may need to instead adjust you thread pool according to server demands to ensure you don't experience memory pressure.

  Throws:

  java.lang.Exception

  See Also:

  DSRequest.setFreeOnExecute(boolean), DSRequest.execute()

• execute

  public DSResponse execute()
                     throws java.lang.Exception

  Executes this DSRequest and returns a DSResponse. If an application is defined for this request, the execution is dispatched through that application. Otherwise, the execution is dispatched through the DataSource layer.

  Specified by:

  execute in class BaseRequest

  Returns:

  a response that extends BaseResponse

  Throws:

  java.lang.Exception

• addToTemplateContext

  public DSRequest addToTemplateContext(java.lang.String name,
                                        java.lang.Object value)

  Same as the three-argument version, but the third argument (isSnippet) is always false.

  Parameters:

  name - the name of the new object as it should appear in the Velocity namespace

  value - arbitrary Java object

  Returns:

  the DSRequest

• addToTemplateContext

  public DSRequest addToTemplateContext(java.lang.String name,
                                        java.lang.Object value,
                                        boolean isSnippet)

  If you're using the Velocity-based SQL Templating, you can make additional Java objects available to the the template context for this request only by calling this method. To make objects available to every request in a queue, see DSTransaction.addToTemplateContext()

  If you would like to add Java objects to all Velocity templates, you can do so via the Velocity Tools mechanism described here: http://velocity.apache.org/tools/releases/2.0/index.html Just add the velocity tools jars to your deployment and place your tools.xml configuration file in the CLASSPATH (typically WEB-INF/classes).

  The isSnippet parameter controls whether the framework treats the context object as a regular context variable, or a user-defined snippet of text. If isSnippet is true, the context object will be evaluated through Velocity immediately prior to the main Velocity evaluation taking place. This means that you can create context variables that themselves contain variable references, and those references will be correctly resolved in the final output. Read the "User-defined snippets" section of the "customQuerying" article in the client-side docs for more details.

  Parameters:

  name - the name of the new object as it should appear in the Velocity namespace

  value - arbitrary Java object

  isSnippet - Is the context object a user-defined snippet?

  Returns:

  the DSRequest

• addToScriptContext

  public DSRequest addToScriptContext(java.lang.String name,
                                      java.lang.Object value)

  If you're using any of the script-based, server-side request or response transformation features - transformRequestScript, transformResponseScript or fieldValueScript - you can make additional Java objects available to the script, for this request only, by calling this method. To make objects available to every request in a queue, see DSTransaction.addToScriptContext()

  For example, set up a string in Java code:

       dsRequest.addToScriptContext("mySimpleString", "This is a test");
   

  and then use that string in your transformation script:

       <DataSource ID="myDS">
           <transformResponseScript language="groovy">
               // Add a property to the response object
               responseObject["testingTransform"] = mySimpleString;
               . . .
           </transformResponseScript>
           . . .
       </DataSource>

  Parameters:

  name - the name of the new object as it should be made available to the script

  value - arbitrary Java object

  Returns:

  the DSRequest