DSRequest

Overview

Package

Class

Tree

Deprecated

Index

Help

PREV CLASS NEXT CLASS

FRAMES NO FRAMES

SUMMARY: NESTED | FIELD | CONSTR | METHOD

DETAIL: FIELD | CONSTR | METHOD

com.isomorphic.datasource
Class DSRequest

com.isomorphic.datasource.DSRequest

public class 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 by either:

creating an RPCManager and calling com.isomorphic.rpc.RPCManager.getDSRequest or com.isomorphic.rpc.RPCManager.getRequests.
using the DMI system (direct method invocation) simply declaring a DSRequest as a parameter of a method that will be invoked via DMI (see DMI topic in client-side reference).

DSRequests can also be used entirely server-side. Your server-side Java code can create a DSRequest via "new DSRequest()" at any time, and call execute() on it in order to perform operations against DataSources. These requests are processed by SmartClient Server exactly as if they had come from the client.

If you are integrating SmartClient with a pre-existing Java data store, you can call various getters on the DSRequest, such as DSRequest.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:

use DSRequest.getCriteria() to retrieve the primary key for the object being updated, and fetch that object from your ORM system
use DSRequest.getValues() in combination with DataTools.setProperties() to apply new properties to the object, based on the Java Beans naming convention
store the modified object using your ORM system

Built-in connectors: SQL, Hibernate and JPA

The SmartClient Server can also automatically process DSRequests from DataSources with serverType="sql", "hibernate" or "jpa". In this case, you can call DSRequest.execute() to cause the default behavior to occur, which will return a DSResponse populated with data supplied by JPA, 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 persistence engine 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.

See Also:: 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.
`RPCManager`	`rpc` Deprecated.

Constructor Summary
`DSRequest(java.lang.String dataSourceName, java.lang.String operationType)` Creates an empty DSRequest bound to the named datasource with the specified operationType.
`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.

Method Summary
`DSRequest`	`addToCriteria(java.lang.String fieldName, java.lang.String operator, java.lang.Object value)` Adds a criterion of the form { fieldName operator value } to this DSRequest's existing criteria.
`DSRequest`	`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.
`DSRequest`	`clearUploadedFiles()` Clears any uploaded files from this DSRequest.
`DSResponse`	`execute()` Executes this DSRequest and returns a DSResponse.
`java.util.List`	`getAdditionalOutputs()` Creates and returns a list of `DSField`s specified in this DSRequest's "additionalOutputs" property.
`AdvancedCriteria`	`getAdvancedCriteria()` Returns the advanced criteria for this operation.
`java.lang.Object`	`getAttribute(java.lang.String key)` Returns an Object that has previously been stored in this DSRequest's attribute map.
`java.util.Iterator`	`getAttributeNames()` Returns an Iterator that can be used to obtain all the keys in the DSRequest's attribute map.
`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.
`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.
`java.lang.String`	`getComponentId()` Optional componentId passed by the client.
`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.
`java.util.List`	`getCriteriaSets()` Returns the `criteria` in the request as a List, even if singular.
`java.lang.Object`	`getCriteriaValue(java.lang.Object fieldName)` Returns the value provided in criteria for a particular fieldName.
`java.lang.String`	`getDataFormat()` Resturns data format for REST request. Possible values: "xml" and "json".
`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.io.OutputStream`	`getExportTo()` Returns the OuputStream we will use for data export.
`java.lang.Object`	`getFieldValue(java.lang.Object fieldName)` Returns the value for a particular fieldName.
`javax.servlet.http.HttpServletRequest`	`getHttpServletRequest()` Returns the HttpServletRequest associated with this DSRequest.
`boolean`	`getIsAdvancedCriteria()` Check if current criteria is advanced.
`java.lang.String`	`getJsonPrefix()` Returns prefix marker for JSON responses.
`java.lang.String`	`getJsonSuffix()` Returns suffix marker for JSON responses.
`java.util.List`	`getMissingPrimaryKeysForAdd()` Validates that this DSRequest has a value present for every non-generated primaryKey.
`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.
`java.util.List`	`getOldValueSets()` Returns the `oldValues` in the request as a List, even if singular.
`java.lang.String`	`getOperationId()` Optional operationId passed by the client.
`java.lang.String`	`getOperationType()` Returns the type of this DataSource operation.
`java.util.List`	`getOutputs()` Returns the list of output fields requested by the client, or configured in the operationBinding.
`boolean`	`getPendingAddFlag()` Returns the pendingAdd flag associated with this DSRequest
`java.lang.Boolean`	`getREST()` Resturns `true` if it is REST request.
`RPCManager`	`getRPCManager()` Returns the RPCManager associated with this DSRequest, if there is one.
`javax.servlet.ServletContext`	`getServletContext()` Returns the ServletContext associated with this DSRequest.
`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).
`java.lang.String`	`getTextMatchStyle()` Returns the textMatchStyle in force for this DSRequest, or null if none is set.
`ISCFileItem`	`getUploadedFile(java.lang.String fieldName)`
`java.util.List`	`getUploadedFiles()`
`java.io.InputStream`	`getUploadedFileStream(java.lang.String fieldName)`
`java.util.List`	`getUploadedFileStreams()`
`java.lang.String`	`getValidationMode()` Returns the validationMode associated with this DSRequest
`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.
`java.util.List`	`getValueSets()` Returns the `values` in the request as a List, even if singular.
`java.lang.Boolean`	`getWrapJSONResponses()` Returns `true` if JSON responses should be wrapped with markers.
`boolean`	`isPaged()` Returns true if the current request has is requestinga partial set of data using startRow/endRow parameters.
`DSRequest`	`removeAttribute(java.lang.String key)` Removes an Object that has previously been stored in this DSRequest's attribute map.
`DSRequest`	`setAdvancedCriteria(AdvancedCriteria advancedCriteria)` Sets the criteria for this request to the provided AdvancedCriteria.
`DSRequest`	`setAllowMultiUpdate(boolean newValue)` Sets an internal flag for this DSRequest to determine whether updates and deletes are allowed in the absence of primaryKey fields.
`DSRequest`	`setAttribute(java.lang.String key, java.lang.Object value)` Stores an object in this DSRequest's attribute map, associated with the passed key.
`DSRequest`	`setCriteria(java.lang.Object criteria)` Sets the criteria for this DSRequest.
`DSRequest`	`setCriteria(java.lang.String fieldName, java.lang.Object value)` Sets the criteria for this DSRequest.
`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.
`DSRequest`	`setDataFormat(java.lang.String dataFormat)` Sets data format for REST request.
`DSRequest`	`setEndRow(long endRow)` Sets the index of the last requested record.
`DSRequest`	`setExportAs(java.lang.String exportAs)` The format in which to export data.
`DSRequest`	`setExportDelimiter(java.lang.String exportDelimiter)` The delimiter to use for CSV-type exports
`DSRequest`	`setExportDisplay(java.lang.String exportDisplay)` How should the exported data be displayed to the user? If not provided, the default is "window".
`DSRequest`	`setExportFields(java.util.List exportFields)` The list of fields to export.
`DSRequest`	`setExportFieldTitles(java.util.Map exportFieldTitles)` A map containing the titles to use for each field to be exported.
`DSRequest`	`setExportFilename(java.lang.String exportFilename)` The name of the file to save the exported data into.
`DSRequest`	`setExportFooter(java.lang.String exportFooter)` Optional text to appear at the bottom of the export file.
`DSRequest`	`setExportHeader(java.lang.String exportHeader)` Optional text to appear at the top of the export file.
`DSRequest`	`setExportHeaderless(boolean exportHeaderless)` This property allows omitting column names from CSV and Excel exports (no effect on JSON or XML exports).
`DSRequest`	`setExportPath(java.lang.String exportPath)` Optional path to apply when saving exported data to the filesystem, relative to the base location specified in server.properties setting "export.location"
`DSRequest`	`setExportResults(java.lang.Boolean exportResults)` Set the flag indicating whether the results of this request should be exported
`DSRequest`	`setExportTitleSeparatorChar(java.lang.String exportTitleSeparatorChar)` The separator character to replace spaces with in XML field-titles.
`DSRequest`	`setExportTo(java.io.OutputStream exportOutputStream)` Sets the OuputStream we will use for data export (this means exports to CSV, XML, JSON and Excel formats; PDF exports are "content exports" and are different).
`DSRequest`	`setExportToClient(boolean exportToClient)` If true, we download the exported data to the client.
`DSRequest`	`setExportToFilesystem(boolean exportToFilesystem)` If true, we export the data to the file named by property`exportFilename` on the server filesystem.
`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.
`DSRequest`	`setFreeOnExecute(boolean freeOnExecute)` Ordinarily, this value is managed transparently by the RPCManager controlling the queue that the DSRequest is part of.
`DSRequest`	`setJoinTransaction(java.lang.Boolean newValue)` Sets the join transaction setting for this DSRequest.
`DSRequest`	`setJsonPrefix(java.lang.String jsonPrefix)` Sets prefix marker for JSON responses.
`DSRequest`	`setJsonSuffix(java.lang.String jsonSuffix)` Sets suffix marker for JSON responses.
`DSRequest`	`setLineBreakStyle(java.lang.String lineBreakStyle)` The linebreak style in the exported data.
`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).
`DSRequest`	`setOperationId(java.lang.String operationId)` For server-initiated DSRequests, sets the operationId to control which operationBinding is used when fulfilling the requests.
`DSRequest`	`setOperationType(java.lang.String operationType)` Sets the operation type.
`DSRequest`	`setOutputs(java.util.List outputs)` Sets the list of output fields to be returned by this request.
`DSRequest`	`setPartOfTransaction(boolean newValue)` Call this method to indicate that a user-written operation is participating in the SmartClient-managed transaction.
`DSRequest`	`setPendingAddFlag(boolean pendingAdd)` Sets the pendingAdd flag associated with this DSRequest
`DSRequest`	`setREST(java.lang.Boolean isREST)` Sets flag indicating whether it is REST request.
`DSRequest`	`setRPCManager(RPCManager rpc)` Associates this DSRequest with the specified RPCManager.
`DSRequest`	`setSortBy(java.lang.Object sortBy)` Sets the field or fields to sort by.
`DSRequest`	`setStartRow(long startRow)` Sets the index of the first requested record.
`DSRequest`	`setStreamResults(boolean streamResults)` If true, results will be streamed one record at a time; if false, we will read all records into memory at once
`DSRequest`	`setTextMatchStyle(java.lang.String textMatchStyle)` Sets the textMatchStyle in force for this DSRequest.
`DSRequest`	`setValidationMode(java.lang.String validationMode)` Sets the validationMode associated with this DSRequest
`DSRequest`	`setValues(java.lang.Object values)` Sets the values for this DSRequest.
`DSRequest`	`setWrapJSONResponses(java.lang.Boolean wrapJSONResponses)` Sets flag should JSON responses be wrapped with markers.
`java.lang.Boolean`	`shouldJoinTransaction()` Returns the join transaction setting for this DSRequest.
`ErrorReport`	`validate()` Performs validation on the values in this DSRequest.

Field Detail

rpc

public RPCManager rpc

Deprecated.

This property has public visibility for reasons of backward-compatibility only. Do NOT set this property directly; use the @link{DSRequest.setRPCManager()} API instead. Setting this property directly may lead to resource leaks.

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)

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

setPartOfTransaction

public DSRequest setPartOfTransaction(boolean newValue)

Call this method to indicate that a user-written operation is participating in the SmartClient-managed transaction. Note that this is just a notification for SmartClient's use; it does not cause your user-written code to automatically be part of the transaction. For that, you must ensure that your code uses the transaction object (see @link{BasicDataSource.getTransactionObject()}).

You do not need to call this method on DSRequests that will be fulfilled by built-in Hibernate or SQL functionality, and you should not do so.

If you neglect to call this method on a user-fulfilled DSRequest, it will not affect the transaction; if you use the transaction object to perform the storage operation, it will be part of the transaction regardless. However, SmartClient Server may return misleading status codes to the client in the event of a rollback if this method is not called.

To understand why this is, consider a situation where your JDBC update works correctly; the DSResponse is marked with a success status. However, an error in a later update in the same transaction causes your successful update to be rolled back. Now your update was not successful; it should be marked as STATUS__TRANSACTION_FAILED, so that the client knows that the data has not been persisted. If your code has not called setPartOfTransaction() appropriately, the server has no way of knowing that this step ought to take place.

Returns:: the DSRequest
See Also:: BasicDataSource.getTransactionObject()

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

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 getAdvancedCriteria to retrieve an AdvancedCriteria which provides simple APIs for manipulating criteria. The modified criteria can be applied to the DSRequest via setAdvancedCriteria.

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 setAdvancedCriteria with AdvancedCriteria helper classes: AdvancedCriteria exists to assist in modifying the criteria.

If AdvancedCriteria passed to this method setAdvancedCriteria 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:: fileName - 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:: fileName - 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:: com.isomorphic.servlet.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:: com.isomorphic.servlet.ISCFileItem.getInputStream()

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.

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.

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:: values - Map - the old values to use for this DSRequest
Returns:: the DSRequest

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 curent 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.
Returns:: the DSRequest
See Also:: DSRequest.getSortByFields()

isPaged

public boolean isPaged()

Returns true if the current request has is requestinga 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

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

getFieldValue

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

Returns the value for a particular 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.

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 setCriteriaValue were called

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

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.

Throws:: java.lang.Exception

addToTemplateContext

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

Parameters:: name - the name of the new object as it should appear in the Velocity namespace; value - arbitrary Java object
Returns:: the DSRequest

setAllowMultiUpdate

public DSRequest setAllowMultiUpdate(boolean newValue)

Sets an internal flag for this DSRequest to determine whether updates and deletes are allowed in the absence of primaryKey fields. The default of false:

prevents client-side requests making sweeping DB changes even if server code isn't written to carefully enforce what can be updated
provides safeguards for server code
allows convenient updates and deletes where you just pass the record in question and rely on the DataSource layer to extract primaryKeys

Note that this property is mainly intended for use with DSRequests that are created by hand on the server side. For ordinary DSRequests that come from the client, the ability to do multi-updates is more conveniently controlled by creating an operationBinding with the allowMultiUpdate property set. See the client-side documentation for OperationBinding for details. Note that operationBinding.allowMultiUpdate, if present, takes priority over this method.

Parameters:: newValue - true to allow multi-updates; false to restrict updates so that they can affect just one single record, identified by primaryKey values in the record provided
Returns:: the DSRequest

getOutputs

public java.util.List getOutputs()

Returns the list of output fields requested by the client, or configured in the operationBinding. Will return null if outputs are not configured, meaning all fields should be returned.

Returns:: List the list of requested outputs as a List of String, or null

setOutputs

public DSRequest setOutputs(java.util.List outputs)

Sets the list of output fields to be returned by this request. If passed null, resets the list of fields to return so that normal rules apply (so basically all fields are returned - scan the client-side docs for "dropExtraFields" for more information).

This method is called during DSRequest construction to set the list of output fields requested by the client, or configured in the operationBinding. Therefore, you can call this method from a DMI, custom DataSource or other custom server side code to override the output fields requested by the client or configured declaratively.

Parameters:: outputs - the list of requested outputs as a List of String, or null
Returns:: the DSRequest itself

getAdditionalOutputs

public java.util.List getAdditionalOutputs()

Creates and returns a list of DSFields specified in this DSRequest's "additionalOutputs" property. "additionalOutputs" is a comma separated String of requested fields not defined in the dataSource directly. The field is defined in the form of "fieldName:includeFrom".

Returns:: List of DSFields specified in the DSRequest's "additionalOutputs" property.

setExportResults

public DSRequest setExportResults(java.lang.Boolean exportResults)

Set the flag indicating whether the results of this request should be exported

Parameters:: exportResults - true if results are to be exported
Returns:: the DSRequest

setExportAs

public DSRequest setExportAs(java.lang.String exportAs)

The format in which to export data. If unset, the default is "csv".

Parameters:: exportAs - one of "csv", "xml", "json", "xls"
Returns:: the DSRequest

setExportDelimiter

public DSRequest setExportDelimiter(java.lang.String exportDelimiter)

The delimiter to use for CSV-type exports

Parameters:: exportDelimiter - the character to use as a delimiter in CSV exports
Returns:: the DSRequest

setExportTitleSeparatorChar

public DSRequest setExportTitleSeparatorChar(java.lang.String exportTitleSeparatorChar)

The separator character to replace spaces with in XML field-titles.

Parameters:: exportTitleSeparatorChar - the character to replace spaces with in XML field-titles.
Returns:: the DSRequest

setExportFilename

public DSRequest setExportFilename(java.lang.String exportFilename)

The name of the file to save the exported data into. When none is provided, the default is "Results".

Parameters:: exportFilename - the name of the file to save the exported data into
Returns:: the DSRequest

setExportPath

public DSRequest setExportPath(java.lang.String exportPath)

Optional path to apply when saving exported data to the filesystem, relative to the base location specified in server.properties setting "export.location"

Parameters:: exportPath - Path to apply
Returns:: the DSRequest

setExportDisplay

public DSRequest setExportDisplay(java.lang.String exportDisplay)

How should the exported data be displayed to the user? If not provided, the default is "window".

Parameters:: exportDisplay - one of "window" or "download"
Returns:: the DSRequest

setLineBreakStyle

public DSRequest setLineBreakStyle(java.lang.String lineBreakStyle)

The linebreak style in the exported data. One of "default", "unix, "mac" or "dos".

Parameters:: lineBreakStyle - the linebreak style to use in the exported data
Returns:: the DSRequest

setExportFields

public DSRequest setExportFields(java.util.List exportFields)

The list of fields to export.

Parameters:: exportFields - the list of field-names to export
Returns:: the DSRequest

setExportFieldTitles

public DSRequest setExportFieldTitles(java.util.Map exportFieldTitles)

A map containing the titles to use for each field to be exported.

Parameters:: exportFields - the list of field-names to export
Returns:: the DSRequest

setExportHeader

public DSRequest setExportHeader(java.lang.String exportHeader)

Optional text to appear at the top of the export file.

Parameters:: exportHeader - Optional text to appear above the data
Returns:: the DSRequest

setExportHeaderless

public DSRequest setExportHeaderless(boolean exportHeaderless)

This property allows omitting column names from CSV and Excel exports (no effect on JSON or XML exports).

Parameters:: exportHeaderless - If true, the column names will be omitted from CSV and Excel exports.
Returns:: the DSRequest

setExportFooter

public DSRequest setExportFooter(java.lang.String exportFooter)

Optional text to appear at the bottom of the export file.

Parameters:: exportFooter - Optional text to appear below the data
Returns:: the DSRequest

setStreamResults

public DSRequest setStreamResults(boolean streamResults)

If true, results will be streamed one record at a time; if false, we will read all records into memory at once

Parameters:: streamResults - true to cause data to be streamed
Returns:: the DSRequest

setExportToFilesystem

public DSRequest setExportToFilesystem(boolean exportToFilesystem)

If true, we export the data to the file named by propertyexportFilename on the server filesystem. See also @link(com.isomorphic.datasource.DSRequest#setExportToClient)

Parameters:: exportToFilesystem - true to cause the export data to be written to the server filesystem
Returns:: the DSRequest

setExportToClient

public DSRequest setExportToClient(boolean exportToClient)

If true, we download the exported data to the client. If

Parameters:: exportToClient - true to cause the exported data to be downloaded to the client
Returns:: the DSRequest

getExportTo

public java.io.OutputStream getExportTo()

Returns the OuputStream we will use for data export. If you have not set this explicitly with the com.isomorphic.datasource.DSResponse#exportTo(OutputStream) API, it will be null.

Returns:: The export OutputStream

setExportTo

public DSRequest setExportTo(java.io.OutputStream exportOutputStream)

Sets the OuputStream we will use for data export (this means exports to CSV, XML, JSON and Excel formats; PDF exports are "content exports" and are different). This API allows you to arrange for other export scenarios than the two built-in options (download to client and write to filesystem). If you set this property, it overrides the default OutputStream we would normally create for a filesystem export; in other words, we will export to your OutputStream rather than to a filesystem file.

Also note that we perform the export synchronously as part of the DSRequest's execute flow when a user-provided OutputStream is in place. This allows you to make use of the OutputStream immediately after executing the request from a DMI, like this:

   OutputStream myStream = new MyOutputStream();
   dsRequest.setExportTo(myStream);
   DSResponse resp = dsRequest.execute();
   // Do something with "myStream" here

Parameters:: exportOutputStream - An OutputStream to use for the export
Returns:: The DSRequest itself

getREST

public java.lang.Boolean getREST()

Resturns true if it is REST request.

Returns:: Boolean true - REST request.

setREST

public DSRequest setREST(java.lang.Boolean isREST)

Sets flag indicating whether it is REST request.

Parameters:: isREST - Boolean true - REST request.
Returns:: the DSRequest

getDataFormat

public java.lang.String getDataFormat()

Resturns data format for REST request.
Possible values: "xml" and "json".

Returns:: String REST request data format.

setDataFormat

public DSRequest setDataFormat(java.lang.String dataFormat)

Sets data format for REST request.

Parameters:: jsonSuffix - String REST request data format. Accepted values: 'xml' or 'json'.
Returns:: the DSRequest

getWrapJSONResponses

public java.lang.Boolean getWrapJSONResponses()

Returns true if JSON responses should be wrapped with markers.

Returns:: Boolean true - JSON responses will be wrapped with markers; false - JSON responses will contain plain objects.

setWrapJSONResponses

public DSRequest setWrapJSONResponses(java.lang.Boolean wrapJSONResponses)

Sets flag should JSON responses be wrapped with markers.

Parameters:: wrapJSONResponses - boolean true - JSON responses will be wrapped with markers; false - JSON responses will contain plain objects.
Returns:: the DSRequest

getJsonPrefix

public java.lang.String getJsonPrefix()

Returns prefix marker for JSON responses.

Returns:: String JSON prefix marker.

setJsonPrefix

public DSRequest setJsonPrefix(java.lang.String jsonPrefix)

Sets prefix marker for JSON responses.

Parameters:: jsonSuffix - String JSON prefix marker.
Returns:: the DSRequest

getJsonSuffix

public java.lang.String getJsonSuffix()

Returns suffix marker for JSON responses.

Returns:: String JSON suffix marker.

setJsonSuffix

public DSRequest setJsonSuffix(java.lang.String jsonSuffix)

Sets suffix marker for JSON responses.

Parameters:: jsonSuffix - String JSON suffix marker.
Returns:: the DSRequest

getRPCManager

public RPCManager getRPCManager()

Returns the RPCManager associated with this DSRequest, if there is one. Note that a DSRequest does not need to operate in the context of an RPCManager, and this method will return null unless you are running in the context of a web application. It is not recommended that you use this value for systems where there is any chance of having to operate outside of a web app, or be usable with automated test software.

Returns:: The RPCManager to use for this request, or null if this request is not running in the context of a web application

getHttpServletRequest

public javax.servlet.http.HttpServletRequest getHttpServletRequest()

Returns the HttpServletRequest associated with this DSRequest. Note that a DSRequest does not need to operate in the context of the Servlet API; this method will return null if you are not running in a servlet container. It is not recommended that you use this value for systems where there is any chance of having to operate outside of a web app, or be usable with automated test software.

Returns:: The HttpServletRequest to use for this request, or null if this request is not running in the context of a web application

getServletContext

public javax.servlet.ServletContext getServletContext()

Returns the ServletContext associated with this DSRequest. Note that a DSRequest does not need to operate in the context of the Servlet API; this method will return null if you are not running in a servlet container. It is not recommended that you use this value for systems where there is any chance of having to operate outside of a web app, or be usable with automated test software.

Returns:: The ServletContext to use for this request, or null if this request is not running in the context of a web application

setRPCManager

public DSRequest setRPCManager(RPCManager rpc)

Associates this DSRequest with the specified RPCManager. For hand-created DSRequests (ie, created in your Java code with "new DSRequest()"), you need to call this method to enable Spring-based DMI and other logic that depends on the current servlet environment, and to have the DSRequest participate the current automatic transaction (if any).

Note that there is also a convenience constructor that allows you to pass an RPCManager in during construction.

Note that setting an RPCManager on a server-created DSRequest causes that DSRequest to begin behaving as if it had come from the client; one effect of this is that update and remove operations are rejected unless the DSRequest correctly specifies primaryKey fields (this restriction is not usually enforced for server-side DSRequests). If you need to correct this side-effect, you can use setAllowMultiUpdate().

Parameters:: rpcManager - The RPCManager to use for this request
Returns:: the DSRequest
See Also:: com.isomorphic.rpc.RPCManager.setAllowMultiUpdate

getAttribute

public java.lang.Object getAttribute(java.lang.String key)

Returns an Object that has previously been stored in this DSRequest's attribute map. This method intentionally mirrors the method of the same name available on HttpServletRequest, and is provided as an alternative way to add objects to a DSRequest without introducing a dependency on the Servlet API.

Parameters:: key - The key of the object in the DSRequest's attribute map
Returns:: the Object associated with the parameter key
See Also:: com.isomorphic.rpc.RPCManager.getAttribute

getAttributeNames

public java.util.Iterator getAttributeNames()

Returns an Iterator that can be used to obtain all the keys in the DSRequest's attribute map. This method intentionally mirrors the method of the same name available on HttpServletRequest (though it returns an Iterator rather than an Enumeration), and is provided as an alternative way to add objects to a DSRequest without introducing a dependency on the Servlet API.

Returns:: an Iterator that can be used to obtain all the keys in the DSRequest's attribute map
See Also:: com.isomorphic.rpc.RPCManager.getAttribute

setAttribute

public DSRequest setAttribute(java.lang.String key,
                              java.lang.Object value)

Stores an object in this DSRequest's attribute map, associated with the passed key. This method intentionally mirrors the method of the same name available on HttpServletRequest, and is provided as an alternative way to add objects to a DSRequest without introducing a dependency on the Servlet API.

Parameters:: key - The key of the object in the DSRequest's attribute map; value - The object to store
Returns:: the DSRequest
See Also:: com.isomorphic.rpc.RPCManager.setAttribute

removeAttribute

public DSRequest removeAttribute(java.lang.String key)

Removes an Object that has previously been stored in this DSRequest's attribute map. This method intentionally mirrors the method of the same name available on HttpServletRequest. It is provided as an alternative, to avoid introducing a dependency on the Servlet API.

Parameters:: key - The key of the object in the DSRequest's attribute map
See Also:: com.isomorphic.rpc.RPCManager.removeAttribute

shouldJoinTransaction

public java.lang.Boolean shouldJoinTransaction()

Returns the join transaction setting for this DSRequest. DSRequests running in a request queue can be configured so that they are committed as a single database transaction. Ordinarily, this is configured in SmartClient .properties files, or in DataSource definitions. However, it is possible to override these configuration settings by calling setJoinTransaction, which overrides any setting derived from configuration.

This method is only applicable to DSRequests for a DataSource that supports transaction management. SmartClient's built-in SQL and Hibernate DataSources both have transaction support. If you intend to write a DataSource trhat supports transactions, you should call this method to determine if user code has overridden configuration settings for this DSRequest.

See the client-side documentation for details of configuring automatic transaction support.

Returns:: Boolean.TRUE or Boolean.FALSE is this DSRequests join policy has been overriddden; null if the normal system behavior of using configuration settings is in force

setJoinTransaction

public DSRequest setJoinTransaction(java.lang.Boolean newValue)
                             throws DSRequestAlreadyStartedException

Sets the join transaction setting for this DSRequest. DSRequests running in a request queue can be configured so that they are committed as a single database transaction. Ordinarily, this is configured in SmartClient .properties files, or in DataSource definitions. However, it is possible to override these configuration settings by calling this method, which overrides any setting derived from configuration. It also overrides any RPCManager-level override that has been put in place for this particular queue by calling setTransactionPolicy

For a manually created dsRequest (one not sent by the client), in order to participate in the current automatic transaction, setRPCManager must be called. Then, the dsRequest will automatically participate in the current automatic transaction (if there is one) without the need to call this method.

This method is only applicable to DSRequests for a DataSource that supports transaction management. SmartClient's built-in SQL and Hibernate DataSources both have transaction support.

Note that this method can only be called on a DSRequest that has not yet started processing; it will fail with an exception if it is called on a request that has already started.

See the client-side documentation for details of configuring automatic transaction support.

Parameters:: Boolean.TRUE - to force this DSRequest's update to start or join a transaction; Boolean.FALSE to force this DSRequest's update to be auto-committed independently of any other update in the queue; null to revert to configuration settings (this is the default if this method is never called)
Returns:: the DSRequest
Throws:: DSRequestAlreadyStartedException - if this DSRequest has already started processing
See Also:: shouldJoinTransaction

setFreeOnExecute

public DSRequest setFreeOnExecute(boolean freeOnExecute)

Ordinarily, this value is managed transparently by the RPCManager controlling the queue that the DSRequest is part of. The only time you should consider using it in application code is when you have entirely server-side DSRequests, because these will not be managed by an RPCManager.

If you pass true to this method, it causes resources used by the DSRequest (including the DataSource object and implementation-specific resources such as database connections) to be freed early - as soon as the DSRequest has finished executing. If you pass false, it causes those resource to be freed late - during final cleanup by the RPCManager in the normal case, but for server-only DSRequests, by your own code or, failing that, by the DSRequest's finalizer.

Generally, you should use freeOnExecute(true) - the default- as this is the most efficient thing to do. However, there are time when you need the resources to be retained - for example, if you have a server-side DSRequest that streams its results.

Parameters:: true - or false, as described above
Returns:: the DSRequest

addToCriteria

public DSRequest addToCriteria(java.lang.String fieldName,
                               java.lang.String operator,
                               java.lang.Object value)
                        throws java.lang.Exception

Adds a criterion of the form { fieldName operator value } to this DSRequest's existing criteria. This method is used by the transaction chaining feature to apply criteria additions; it can also be called by arbitrary server-side code to add a criterion to simple or AdvancedCriteria.

If the DSRequest's criteria is simple and the operator is "equals" or null, this method just adds the provided fieldName and value as an extra key/value pair in the simple criteria map. If the DSRequest's criteria is simple and the operator is some other value, the simple criteria is converted to an equivalent AdvancedCriteria and then processed as if the criteria had been Advanced all along, which is to amend the criteria as follows:

If the topmost operator is "and", we add the new criterion described above as an additional criterion.
Otherwise, we create a new top-level AdvancedCriteria map, with an operator of "and". This is then set to have two elements to its criteria: the previous top-level criteria and the new criterion described above.

Hence, in all cases, the effect is to apply the new criterion as an extra condition that must be met in order for a record to be selected.

Parameters:: fieldName - The field name to use in the criteria; value - The filter value to apply
Returns:: the DSRequest
Throws:: java.lang.Exception

getMissingPrimaryKeysForAdd

public java.util.List getMissingPrimaryKeysForAdd()
                                           throws java.lang.Exception

Validates that this DSRequest has a value present for every non-generated primaryKey. During "add" operations, it is valid (and sometimes even required, depending on the database in use) for fields of type "sequence" to be missing from the values, but all other types of primaryKey must be present. This method is called by SmartClient Server's built-in DataSource implementations immediately before they generate SQL/HQL/JPQL. in order to give custom server-side code in DMIs and Custom DataSource subclasses a chance to add key values to the request before rejecting it.

In a completely custom DataSource (ie, one that extends BasicDataSource), you should add a call to this method if you want the protection it provides against null key values. The simplest thing to do is what the built-in DataSources do - throw an UpdateWIthoutPKException if this method returns a non-empty List.

Note that this method honors the operationBinding setting "allowMultiUpdate" - if that property is set for the operation this DSRequest is running, this method always returns anh empty List. Also, it is possible to switch off key checking for "add" operations altogether by setting the property validate.primaryKeys.for.add to false in your server.properties file.

Returns:: the List of non-generated primaryKey fields that are missing from this DSRequest, or an empty List if there are no such fields, or key checking is inoperative either globally or for the operationBinding currently in force
Throws:: java.lang.Exception

Overview

Package

Class

Tree

Deprecated

Index

Help

PREV CLASS NEXT CLASS

FRAMES NO FRAMES

SUMMARY: NESTED | FIELD | CONSTR | METHOD

DETAIL: FIELD | CONSTR | METHOD

com.isomorphic.datasource Class DSRequest

rpc

ENDROW_UNSET

DSRequest

DSRequest

setPartOfTransaction

getTextMatchStyle

setTextMatchStyle

getOperationType

setOperationType

getOperationId

setOperationId

getComponentId

getCriteria

getAdvancedCriteria

getIsAdvancedCriteria

setAdvancedCriteria

getClientSuppliedCriteria

getCriteriaSets

setCriteria

setCriteria

clearUploadedFiles

getUploadedFile

getUploadedFiles

getUploadedFileStream

getUploadedFileStreams

getValues

getClientSuppliedValues

getValueSets

setValues

getOldValues

getOldValueSets

setOldValues

getSortByFields

setSortBy

isPaged

getStartRow

setStartRow

getEndRow

setEndRow

getFieldValue

getCriteriaValue

setCriteriaValue

setFieldValue

getDataSourceName

getDataSource

getValidationMode

setValidationMode

getPendingAddFlag

setPendingAddFlag

validate

execute

addToTemplateContext

setAllowMultiUpdate

getOutputs

setOutputs

getAdditionalOutputs

setExportResults

setExportAs

setExportDelimiter

setExportTitleSeparatorChar

setExportFilename

setExportPath

setExportDisplay

setLineBreakStyle

setExportFields

setExportFieldTitles

setExportHeader

setExportHeaderless

setExportFooter

setStreamResults

setExportToFilesystem

setExportToClient

getExportTo

setExportTo

getREST

setREST

getDataFormat

setDataFormat

getWrapJSONResponses

com.isomorphic.datasource
Class DSRequest