Possible values: "xml" and "json".
DataSource
getDataSource()
java.lang.String
getDataSourceName()
java.util.List
getDroppedFields()
long
getEndRow()
boolean
getExportResults()
java.io.OutputStream
getExportTo()
java.lang.Object
getFieldValue(java.lang.Object fieldName)
java.lang.Boolean
getGenerateRelatedUpdates()
DSResponse
.java.util.List
getGroupBy()
javax.servlet.http.HttpServletRequest
getHttpServletRequest()
boolean
getIncludeBinaryFields()
boolean
getIsAdvancedCriteria()
java.lang.String
getJsonPrefix()
java.lang.String
getJsonSuffix()
java.util.List
getMissingPrimaryKeysForAdd()
java.util.Map
getOldValues()
java.util.List
getOldValueSets()
oldValues
in the request as a List, even if singular.java.lang.String
getOperationId()
java.lang.String
getOperationType()
java.util.List
getOutputs()
DSRequest.setOutputs(java.util.List)
.boolean
getPendingAddFlag()
java.lang.Boolean
getREST()
true
if it is REST request.RPCManager
getRPCManager()
javax.servlet.ServletContext
getServletContext()
java.lang.String
getSortBy()
java.util.List
getSortByFields()
long
getStartRow()
java.util.Map
getSummaryFunctions()
java.lang.String
getTextMatchStyle()
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()
java.util.Map
getValues()
java.util.List
getValueSets()
values
in the request as a List, even if singular.java.lang.Boolean
getWrapJSONResponses()
true
if JSON responses should be wrapped with markers.boolean
isPaged()
DSRequest
removeAttribute(java.lang.String key)
DSRequest
setAdvancedCriteria(AdvancedCriteria advancedCriteria)
DSRequest
setAllowMultiUpdate(boolean newValue)
DSRequest
setAttribute(java.lang.String key, java.lang.Object value)
void
setCanSyncCache(boolean canSyncCache)
DSRequest
setCriteria(java.lang.Object criteria)
DSRequest
setCriteria(java.lang.String fieldName, java.lang.Object value)
java.lang.Object
setCriteriaValue(java.lang.String fieldName, java.lang.Object value)
DSRequest
setDataFormat(java.lang.String dataFormat)
DSRequest
setEndRow(long endRow)
DSRequest
setExportAs(java.lang.String exportAs)
DSRequest
setExportDelimiter(java.lang.String exportDelimiter)
DSRequest
setExportDisplay(java.lang.String exportDisplay)
DSRequest
setExportFields(java.util.List exportFields)
DSRequest
setExportFieldTitles(java.util.Map exportFieldTitles)
DSRequest
setExportFilename(java.lang.String exportFilename)
DSRequest
setExportFooter(java.lang.String exportFooter)
DSRequest
setExportHeader(java.lang.String exportHeader)
DSRequest
setExportHeaderless(boolean exportHeaderless)
DSRequest
setExportPath(java.lang.String exportPath)
DSRequest
setExportResults(java.lang.Boolean exportResults)
DSRequest
setExportTitleSeparatorChar(java.lang.String exportTitleSeparatorChar)
DSRequest
setExportTo(java.io.OutputStream exportOutputStream)
DSRequest
setExportToClient(boolean exportToClient)
DSRequest
setExportToFilesystem(boolean exportToFilesystem)
exportFilename
on the server filesystem.DSRequest
setFieldValue(java.lang.Object fieldName, java.lang.Object value)
DSRequest
setFreeOnExecute(boolean freeOnExecute)
DSRequest
setGroupBy(java.util.List groupBy)
DSRequest
setGroupBy(java.lang.String[] groupBy)
fetch
operation group by fields can be set.void
setIncludeBinaryFields(boolean includeBinaryFields)
DSRequests
that target SQLDataSource
.DSRequest
setJoinTransaction(java.lang.Boolean newValue)
DSRequest
setJsonPrefix(java.lang.String jsonPrefix)
DSRequest
setJsonSuffix(java.lang.String jsonSuffix)
DSRequest
setLineBreakStyle(java.lang.String lineBreakStyle)
DSRequest
setOldValues(java.util.Map oldValues)
DSRequest
setOperationId(java.lang.String operationId)
DSRequest
setOperationType(java.lang.String operationType)
DSRequest
setOutputs(java.util.List outputs)
DSRequest
setPartOfTransaction(boolean newValue)
DSRequest
setPendingAddFlag(boolean pendingAdd)
DSRequest
setREST(java.lang.Boolean isREST)
DSRequest
setRPCManager(RPCManager rpc)
DSRequest
setSortBy(java.lang.Object sortBy)
DSRequest
setStartRow(long startRow)
DSRequest
setStreamResults(boolean streamResults)
DSRequest
setSummaryFunctions(java.util.Map summaryFunctions)
DSRequest
setTextMatchStyle(java.lang.String textMatchStyle)
DSRequest
setValidationMode(java.lang.String validationMode)
DSRequest
setValues(java.lang.Object values)
DSRequest
setWrapJSONResponses(java.lang.Boolean wrapJSONResponses)
java.lang.Boolean
shouldJoinTransaction()
boolean
shouldStreamResults()
ErrorReport
validate()
public RPCManager rpc
public static final long ENDROW_UNSET
DSRequest.getEndRow()
, Constant Field Valuespublic DSRequest(java.lang.String dataSourceName, java.lang.String operationType)
dataSourceName
- name of the datasource for this requestoperationType
- operationType for this requestpublic DSRequest(java.lang.String dataSourceName, java.lang.String operationType, RPCManager rpcManager)
dataSourceName
- name of the datasource for this requestoperationType
- operationType for this requestrpcManager
- The RPCManager in use for this requestpublic DSRequest setPartOfTransaction(boolean newValue)
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:
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. 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:
setPartOfTransaction(false)
right at the top of your DMI method. This would handle transactional failure correctly without any further code to writeSQLTransaction.rollbackTransaction(dsRequest.getRPCManager());
DataSource.getTransactionObject()
public java.lang.String getTextMatchStyle()
public DSRequest setTextMatchStyle(java.lang.String textMatchStyle)
public java.lang.String getOperationType()
public DSRequest setOperationType(java.lang.String operationType)
operationType
- the operation type - see above for valid values.public java.lang.String getOperationId()
The operationId is a means for client-side DataBound Components to request variants of the basic DataSource operations that the server may support, such as normal fetch
operations vs fetch
operations that use a single parameter and do full-text search. See the Client Reference for DSRequest.operationId for more information.
public DSRequest setOperationId(java.lang.String operationId)
operationId
- the operationId to useDSRequest.getOperationId()
public java.lang.String getComponentId()
For requests submitted by a SmartClient DataBoundComponent, this is the component ID.
public java.util.Map getCriteria()
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)
.
DSRequest.getValues()
public AdvancedCriteria getAdvancedCriteria()
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.
public boolean getIsAdvancedCriteria()
AdvancedCriteria has "_constructor" parameter set to "AdvancedCriteria".
public DSRequest setAdvancedCriteria(AdvancedCriteria advancedCriteria)
Note: AdvancedCriteria will only be able to be executed by the built-in server DataSources (JPA, Hibernate, SQL) in Power Edition and above.
advancedCriteria
- the criteria to use for this DSRequestDSRequest.getCriteria()
public java.util.Map getClientSuppliedCriteria()
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.DSRequest.getCriteria()
, DSRequest.getClientSuppliedValues()
public java.util.List getCriteriaSets()
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.
DSRequest.getCriteria()
, DSRequest.getValueSets()
public DSRequest setCriteria(java.lang.Object criteria)
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.
criteria
- Map or List of Maps: the criteria to use for this DSRequestDSRequest.getCriteria()
public DSRequest setCriteria(java.lang.String fieldName, java.lang.Object value)
fieldName
- The field namevalue
- The criterion valueDSRequest.getCriteria()
public DSRequest clearUploadedFiles()
public ISCFileItem getUploadedFile(java.lang.String fieldName) throws java.lang.Exception
fieldName
- Form field of type 'binary'.java.lang.Exception
public java.util.List getUploadedFiles()
public java.io.InputStream getUploadedFileStream(java.lang.String fieldName) throws java.lang.Exception
fieldName
- Form field of type 'binary'.java.lang.Exception
com.isomorphic.servlet.ISCFileItem.getInputStream()
public java.util.List getUploadedFileStreams()
com.isomorphic.servlet.ISCFileItem.getInputStream()
public void setIncludeBinaryFields(boolean includeBinaryFields)
DSRequests
that target SQLDataSource
.By default binary fields are:
includeBinaryFields
- false
to skip selecting binary fieldspublic boolean getIncludeBinaryFields()
public java.util.Map getValues()
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.
DSRequest.getCriteria()
, DSRequest.getOldValues()
, DSRequest.getClientSuppliedValues()
public java.util.Map getClientSuppliedValues()
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.
DSRequest.getCriteria()
, DSRequest.getOldValues()
, DSRequest.getClientSuppliedValues()
public java.util.List getValueSets()
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.
DSRequest.getValues()
, DSRequest.getCriteriaSets()
public DSRequest setValues(java.lang.Object values)
values
- Map or List of Maps - the values to use for this DSRequestpublic java.util.Map getOldValues()
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.
DSRequest.getValues()
public java.util.List getOldValueSets()
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.
DSRequest.getOldValues()
public DSRequest setOldValues(java.util.Map oldValues)
values
- Map - the old values to use for this DSRequestpublic java.lang.String getSortBy()
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.
DSRequest.getSortByFields()
public java.util.List getSortByFields()
This method signature is the generic method that returns all fields for which a sort has been requested. If the list contains more than one entry, then that means the data should be sorted by the first field in the list, then within that first sort data should be sorted by the next field in the list and so on. So the second sortBy field can only affect data that has the same value for the first sortBy field.
The returned value is a List of Strings that are the names of the fields to sort by. If the String is prefixed by a -
then that specifies descending order. Otherwise it's a request for an ascending sort on that field.
A concrete example of when a sortBy is sent by an ISC databound component: Let's say you have a ListGrid that has a partially loaded dataset (the dataset is too large to be on the client at once, so you're only showing, say, the first 100 rows). If you now click on one of the columns to sort by that column, the ListGrid will send a DSRequest to the server with a sortBy fieldName of the field that was clicked on. Since not all data is present on the client, the grid can't do the sort client-side (and still continue to display the first 100 matches to the curent filter criteria).
public DSRequest setSortBy(java.lang.Object sortBy)
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.DSRequest.getSortByFields()
public java.util.List getGroupBy()
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.
List
with field names to group by, or null if no grouping is configuredDSRequest.getSummaryFunctions()
public DSRequest setGroupBy(java.util.List groupBy)
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.
groupBy
- List
with field names to group by.DSRequest.setSummaryFunctions(java.util.Map)
public DSRequest setGroupBy(java.lang.String[] groupBy)
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. groupBy
- String...
with field names to group by.DSRequest.setSummaryFunctions(java.util.Map)
public java.util.Map getSummaryFunctions()
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.
Map
with field names as keys and summary functions as values.DSRequest.getGroupBy()
public DSRequest setSummaryFunctions(java.util.Map summaryFunctions)
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.
summaryFunctions
- Map
with field names as keys and summary functions as values.DSRequest.setGroupBy(java.util.List)
public boolean isPaged()
public long getStartRow()
When multi-record capable components make requests to the server for data, they send the startRow and endRow parameters to indicate the slice of data they need to show to the user right now.
You can use the isPaged() method on this request to check if you need to respect startRow/endRow for this request.
Note that startRow and endRow are zero-based, inclusive at the beginning and exclusive at the end (like substring), so startRow: 0, endRow: 1 is a request for the first record.
DSRequest.getEndRow()
, DSRequest.isPaged()
public DSRequest setStartRow(long startRow)
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.
startRow
- the index of the first requested record (using zero-based numbering)public long getEndRow()
If getEndRow() returns DSRequest.ENDROW_UNSET (a negative value), that signifies a request for all records matching the current criteria.
Note that startRow and endRow are zero-based, inclusive at the beginning and exclusive at the end (like substring), so startRow: 0, endRow: 1 is a request for the first record.
DSRequest.getStartRow()
, DSRequest.ENDROW_UNSET
public DSRequest setEndRow(long endRow)
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.
endRow
- the index of the last requested record (using zero-based numbering)public java.lang.Object getFieldValue(java.lang.Object fieldName)
This is a convenience method. For any given operation, a particular fieldName will usually appear in either the valueSet or criteria.
fieldName
- the fieldName whose value you want to look uppublic java.lang.Object getCriteriaValue(java.lang.Object fieldName)
If AdvancedCriteria
were passed, getCriteriaValue finds the first value provided for the fieldName anywhere in the AdvancedCriteria structure, by depth-first search.
fieldName
- the fieldName whose criteria value you want to look uppublic java.lang.Object setCriteriaValue(java.lang.String fieldName, java.lang.Object value)
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.fieldName
- indicated field of criterionvalue
- required value the field must equalfieldName
is already referenced in the criteria, then the overwritten criterion value; otherwise nullpublic DSRequest setFieldValue(java.lang.Object fieldName, java.lang.Object value)
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
fieldName
- the fieldName whose value you want to setvalue
- the value to set for the fieldpublic java.lang.String getDataSourceName()
public DataSource getDataSource() throws java.lang.Exception
java.lang.Exception
DataSource
, DSRequest.getDataSourceName()
public java.lang.String getValidationMode()
public DSRequest setValidationMode(java.lang.String validationMode)
public boolean getPendingAddFlag()
public DSRequest setPendingAddFlag(boolean pendingAdd)
public ErrorReport validate() throws java.lang.Exception
If validation is successful for all fields, this method returns null. Otherwise it returns an ErrorReport for the first record that encountered a validation error.
java.lang.Exception
ErrorReport
, ErrorMessage
public java.lang.Boolean getGenerateRelatedUpdates()
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
.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.public DSResponse execute() throws java.lang.Exception
java.lang.Exception
public DSRequest addToTemplateContext(java.lang.String name, java.lang.Object value)
name
- the name of the new object as it should appear in the Velocity namespacevalue
- arbitrary Java objectpublic DSRequest setAllowMultiUpdate(boolean newValue)
null
this is controlled by dataSource.defaultMultiUpdatePolicy
, see client docs for details.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 providedpublic java.util.List getOutputs()
DSRequest.setOutputs(java.util.List)
. Will return null if the client did not send a list of outputs and no manual server-side call to setOutputs() has been made. Note that this is not the definitive list of fields to be returned to the client - for that, see DSRequest.getConsolidatedOutputs()
DSRequest.getConsolidatedOutputs()
public DSRequest setOutputs(java.util.List outputs)
This method is called during DSRequest construction to set the list of output fields requested by the client. 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. Not ethat this is not the definitive list of fields to be returned to the client - for that, see DSRequest.getConsolidatedOutputs()
outputs
- the list of requested outputs as a List of String, or nullDSRequest.getConsolidatedOutputs()
public java.util.List getAdditionalOutputs()
DSField
s 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".List
of DSField
s specified in the DSRequest's "additionalOutputs" property.public boolean getExportResults()
public DSRequest setExportResults(java.lang.Boolean exportResults)
exportResults
- true if results are to be exportedpublic DSRequest setExportAs(java.lang.String exportAs)
exportAs
- one of "csv", "xml", "json", "xls"public DSRequest setExportDelimiter(java.lang.String exportDelimiter)
exportDelimiter
- the character to use as a delimiter in CSV exportspublic DSRequest setExportTitleSeparatorChar(java.lang.String exportTitleSeparatorChar)
exportTitleSeparatorChar
- the character to replace spaces with in XML field-titles.public DSRequest setExportFilename(java.lang.String exportFilename)
exportFilename
- the name of the file to save the exported data intopublic DSRequest setExportPath(java.lang.String exportPath)
exportPath
- Path to applypublic DSRequest setExportDisplay(java.lang.String exportDisplay)
exportDisplay
- one of "window" or "download"public DSRequest setLineBreakStyle(java.lang.String lineBreakStyle)
lineBreakStyle
- the linebreak style to use in the exported datapublic DSRequest setExportFields(java.util.List exportFields)
exportFields
- the list of field-names to exportpublic DSRequest setExportFieldTitles(java.util.Map exportFieldTitles)
exportFields
- the list of field-names to exportpublic DSRequest setExportHeader(java.lang.String exportHeader)
exportHeader
- Optional text to appear above the datapublic DSRequest setExportHeaderless(boolean exportHeaderless)
exportHeaderless
- If true, the column names will be omitted from CSV and Excel exports.public DSRequest setExportFooter(java.lang.String exportFooter)
exportFooter
- Optional text to appear below the datapublic DSRequest setStreamResults(boolean streamResults)
streamResults
- true to cause data to be streamedpublic boolean shouldStreamResults()
public DSRequest setExportToFilesystem(boolean exportToFilesystem)
exportFilename
on the server filesystem. See also DSRequest.setExportToClient(boolean)
Note this is automatically set to true
if DSRequest.setExportTo(java.io.OutputStream)
is called.
exportToFilesystem
- true to cause the export data to be written to the server filesystempublic DSRequest setExportToClient(boolean exportToClient)
DSRequest.setExportToFilesystem(boolean)
is also set, we will both download the exported data and write it to a filesystem file on the server. If neither of these is set, the export operation no-ops.exportToClient
- true to cause the exported data to be downloaded to the clientpublic java.io.OutputStream getExportTo()
com.isomorphic.datasource.DSResponse#exportTo(OutputStream)
API, it will be null.public DSRequest setExportTo(java.io.OutputStream exportOutputStream)
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
exportOutputStream
- An OutputStream to use for the exportDSRequest.setExportToFilesystem(boolean)
public java.lang.Boolean getREST()
true
if it is REST request.Boolean
true
- REST request.public DSRequest setREST(java.lang.Boolean isREST)
isREST
- Boolean
true
- REST request.public java.lang.String getDataFormat()
String
REST request data format.public DSRequest setDataFormat(java.lang.String dataFormat)
jsonSuffix
- String
REST request data format. Accepted values: 'xml' or 'json'.public java.lang.Boolean getWrapJSONResponses()
true
if JSON responses should be wrapped with markers.Boolean
true
- JSON responses will be wrapped with markers; false
- JSON responses will contain plain objects.public DSRequest setWrapJSONResponses(java.lang.Boolean wrapJSONResponses)
wrapJSONResponses
- boolean
true
- JSON responses will be wrapped with markers; false
- JSON responses will contain plain objects.public java.lang.String getJsonPrefix()
String
JSON prefix marker.public DSRequest setJsonPrefix(java.lang.String jsonPrefix)
jsonSuffix
- String
JSON prefix marker.public java.lang.String getJsonSuffix()
String
JSON suffix marker.public DSRequest setJsonSuffix(java.lang.String jsonSuffix)
jsonSuffix
- String
JSON suffix marker.public RPCManager getRPCManager()
public javax.servlet.http.HttpServletRequest getHttpServletRequest()
public javax.servlet.ServletContext getServletContext()
public DSRequest setRPCManager(RPCManager rpc)
Note that there is also a convenience constructor that allows you to pass an RPCManager in during construction.
rpcManager
- The RPCManager to use for this requestcom.isomorphic.rpc.RPCManager.setAllowMultiUpdate
public java.lang.Object getAttribute(java.lang.String key)
key
- The key of the object in the DSRequest's attribute mapcom.isomorphic.rpc.RPCManager.getAttribute
public java.util.Iterator getAttributeNames()
com.isomorphic.rpc.RPCManager.getAttribute
public DSRequest setAttribute(java.lang.String key, java.lang.Object value)
Attributes set on the DSRequest are not serialized and sent to the browser. Custom attributes exist solely for passing extra information between different server-side subsystems that might process the DSRequest. For example: Java logic in a DMI might set attributes on a DSRequest to cause differences in processing by a custom DataSource that checks for those attributes.
key
- The key of the object in the DSRequest's attribute mapvalue
- The object to storecom.isomorphic.rpc.RPCManager.setAttribute
public DSRequest removeAttribute(java.lang.String key)
key
- The key of the object in the DSRequest's attribute mapcom.isomorphic.rpc.RPCManager.removeAttribute
public java.lang.Boolean shouldJoinTransaction()
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.
public DSRequest setJoinTransaction(java.lang.Boolean newValue) throws DSRequestAlreadyStartedException
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.
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)DSRequestAlreadyStartedException
- if this DSRequest has already started processingshouldJoinTransaction
public DSRequest freeAllResources()
Typically, there is no need to call freeAllResources
because it is automatically handled by the framework. You only need to call this API when all of the following apply:
setRPCManager()
on the request, ANDsetFreeOnExecute(false)
on the DSRequest, or the default setting of freeOnExecute
is false for this type of request.setRPCManager()
on server-created DSRequests because this is required in order to participate in automatically managed transactions. Regarding 3), any DSRequest that targets a SQLDataSource and retrieves data from a binary column (CLOB) is freeOnExecute:false
by default, since otherwise most JDBC drivers will close the InputStream used to read binary data.
Also, any DSRequest targetting HibernateDataSource or JPADataSource is freeOnExecute:false
by default in order to allow traversing lazy entity associations.
Note that the resources freed by this API are made immediately available to other threads: do not cache DataSource instances or other resources and attempt to reuse them after calling this API. In general, use this API only if you are sure you have to (because you have a DSRequest like the one described above), and even then use it with care; ideally, call it as the last thing you do immediately before your DMI method ends.
public DSRequest setFreeOnExecute(boolean freeOnExecute)
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 if setRPCManager()
has been called, otherwise, when your code manually calls freeAllResources()
, otherwise, by the DSRequest's finalizer when garbage collection occurs.
Generally, you should use freeOnExecute(true)
- the default - as this is the most efficient thing to do. However, there are times when you need the resources to be retained - for example, if you have a server-side DSRequest that streams its results.
See freeAllResources()
for a further discussion of scenarios where immediate cleanup is not desirable.
true
- or false, as described abovepublic java.util.List getConsolidatedOutputs()
DSRequest.getDroppedFields()
DSRequest.getOutputs()
, DSRequest.getDroppedFields()
public java.util.List getDroppedFields()
Note, the list returned by this method is a copy, and thus should be considered read-only.
DSRequest.getConsolidatedOutputs()
public DSRequest addToCriteria(java.lang.String fieldName, java.lang.Object value) throws java.lang.Exception
If the criteria is already Advanced and either:
Note that this is the only version of addToCriteria()
that attempts to automatically preserve simple criteria semantics as described above. If you do not want this behavior, use one of the other signatures of this method.
fieldName
- The field name to use in the criteriavalue
- The filter value to applyjava.lang.Exception
public DSRequest addToCriteria(java.lang.String fieldName, java.lang.String operator, java.lang.Object value) throws java.lang.Exception
five argument signature
of addToCriteria(), passing null for start and end.fieldName
- The field name to use in the criteriaoperator
- The operatorId to usevalue
- The filter value to applyjava.lang.Exception
public DSRequest addToCriteria(java.lang.String fieldName, java.lang.String operator, java.lang.Object[] value) throws java.lang.Exception
fieldName
- The field name to use in the criteriaoperator
- The operatorId to usevalue
- An array of valuesjava.lang.Exception
public DSRequest addToCriteria(java.lang.String fieldName, OperatorBase operator, java.lang.Object value) throws java.lang.Exception
five argument signature
of addToCriteria(), passing null for start and end, and passing the ID operator from the passed OperatorBase as the operator to avoid typos.fieldName
- The field name to use in the criteriaoperator
- The operatorBase to usevalue
- The filter value to applyjava.lang.Exception
public DSRequest addToCriteria(java.lang.String fieldName, OperatorBase operator, java.lang.Object[] value) throws java.lang.Exception
fieldName
- The field name to use in the criteriaoperator
- The operatorBase to usevalue
- An array of valuesjava.lang.Exception
public DSRequest addToCriteria(java.lang.String fieldName, java.lang.String operator, java.lang.Object value, java.lang.Object start, java.lang.Object end) throws java.lang.Exception
two argument signature
of this method. If the DSRequest's criteria is simple, 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:
fieldName
- The field name to use in the criteriaoperator
- The operatorId to usevalue
- The filter value to apply, for comparison operators like "contains"start
- The range-start value to apply, for range operators like "between"end
- The range-end value to apply, for range operators like "between"java.lang.Exception
public DSRequest addToCriteria(Criterion criterion) throws java.lang.Exception
five argument signature
of addToCriteria().criterion
- The criterion to use in the criteriajava.lang.Exception
public java.util.List getMissingPrimaryKeysForAdd() throws java.lang.Exception
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 an 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. Finally, be aware that primaryKey fields that declare a customInsertExpression
are never considered to have "missing values", because it is assumed that the custom expression will cause a value to appear at SQL generation or execution time.
java.lang.Exception
public void setCanSyncCache(boolean canSyncCache)
canSyncCache
-