Force.com Apex Code Developer's Guide

Clouds with binary code floating aboveCloud with binary code floating above

No Results

Search Tips:

  • Please consider misspellings
  • Try different search keywords
PDF

Newer Version Available

This content describes an older version of this product. View Latest

sObject Class

Contains methods for the sObject data type.

Namespace

System

Usage

sObject methods are all instance methods, that is, they are called by and operate on a particular instance of an sObject, such as an account or contact. The following are the instance methods for sObjects.

For more information on sObjects, see sObject Types.

SObject Methods

The following are methods for SObject. All are instance methods.

addError(String)

Marks a record with a custom error message and prevents any DML operation from occurring.

Signature

public Void addError(String errorMsg)

Parameters

errorMsg
Type: String

The error message to mark the record with.

Return Value

Type: Void

Usage

When used on Trigger.new in before insert and before update triggers, and on Trigger.old in before delete triggers, the error message is displayed in the application interface.

See Triggers and Trigger Exceptions.

This method escapes any HTML markup in the specified error message. The escaped characters are: \n, <, >, &, ", \, \u2028, \u2029, and \u00a9. This results in the HTML markup not being rendered; instead it is displayed as text in the Salesforce user interface.

Note

When used in Visualforce controllers, the generated message is added to the collection of errors for the page. For more information, see Validation Rules and Standard Controllers in the Visualforce Developer's Guide.

addError(String, Boolean)

Marks a record with a custom error message, specifies whether or not the error message should be escaped, and prevents any DML operation from occurring.

Signature

public Void addError(String errorMsg, Boolean escape)

Parameters

errorMsg
Type: String

The error message to mark the record with.

escape
Type: Boolean

Indicates whether any HTML markup in the custom error message should be escaped (true) or not (false).

Return Value

Type: Void

Usage

The escaped characters are: \n, <, >, &, ", \, \u2028, \u2029, and \u00a9. This results in the HTML markup not being rendered; instead it is displayed as text in the Salesforce user interface.

Be cautious if you specify false for the escape argument. Unescaped strings displayed in the Salesforce user interface can represent a vulnerability in the system because these strings might contain harmful code. If you want to include HTML markup in the error message, call this method with a false escape argument and make sure you escape any dynamic content, such as input field values. Otherwise, specify true for the escape argument or call addError(String errorMsg) instead.

Warning

addError(Exception)

Marks a record with a custom error message and prevents any DML operation from occurring.

Signature

public Void addError(Exception exceptionError)

Parameters

exceptionError
Type: System.Exception

An Exception object or a custom exception object that contains the error message to mark the record with.

Return Value

Type: Void

Usage

When used on Trigger.new in before insert and before update triggers, and on Trigger.old in before delete triggers, the error message is displayed in the application interface.

See Triggers and Trigger Exceptions.

This method escapes any HTML markup in the specified error message. The escaped characters are: \n, <, >, &, ", \, \u2028, \u2029, and \u00a9. This results in the HTML markup not being rendered; instead it is displayed as text in the Salesforce user interface.

Note

When used in Visualforce controllers, the generated message is added to the collection of errors for the page. For more information, see Validation Rules and Standard Controllers in the Visualforce Developer's Guide.

addError(Exception, Boolean)

Marks a record with a custom exception error message, specifies whether or not the exception error message should be escaped, and prevents any DML operation from occurring.

Signature

public Void addError(Exception exceptionError, Boolean escape)

Parameters

exceptionError
Type: System.Exception

An Exception object or a custom exception object that contains the error message to mark the record with.

escape
Type: Boolean

Indicates whether any HTML markup in the custom error message should be escaped (true) or not (false).

Return Value

Type: Void

Usage

The escaped characters are: \n, <, >, &, ", \, \u2028, \u2029, and \u00a9. This results in the HTML markup not being rendered; instead it is displayed as text in the Salesforce user interface.

Be cautious if you specify false for the escape argument. Unescaped strings displayed in the Salesforce user interface can represent a vulnerability in the system because these strings might contain harmful code. If you want to include HTML markup in the error message, call this method with a false escape argument and make sure you escape any dynamic content, such as input field values. Otherwise, specify true for the escape argument or call addError(Exception e) instead.

Warning

field.addError(String)

Places the specified error message on the field in the Salesforce user interface and prevents any DML operation from occurring.

Signature

public Void addError(String errorMsg)

Parameters

errorMsg
Type: String

Return Value

Type: Void

Usage

Note:
  • When used on Trigger.new in before insert and before update triggers, and on Trigger.old in before delete triggers, the error appears in the application interface.
  • When used in Visualforce controllers, if there is an inputField component bound to field, the message is attached to the component. For more information, see Validation Rules and Standard Controllers in the Visualforce Developer's Guide.
  • This method is highly specialized because the field identifier is not actually the invoking object—the sObject record is the invoker. The field is simply used to identify the field that should be used to display the error.
  • This method will likely change in future versions of Apex.

See Triggers and Trigger Exceptions.

This method escapes any HTML markup in the specified error message. The escaped characters are: \n, <, >, &, ", \, \u2028, \u2029, and \u00a9. This results in the HTML markup not being rendered; instead it is displayed as text in the Salesforce user interface.

Note

Example

1Trigger.new[0].myField__C.addError('bad');

field.addError(String, Boolean)

Places the specified error message, which can be escaped or unescaped, on the field in the Salesforce user interface, and prevents any DML operation from occurring.

Signature

public Void addError(String errorMsg, Boolean escape)

Parameters

errorMsg
Type: String

The error message to mark the record with.

escape
Type: Boolean

Indicates whether any HTML markup in the custom error message should be escaped (true) or not (false).

Return Value

Type:

Usage

The escaped characters are: \n, <, >, &, ", \, \u2028, \u2029, and \u00a9. This results in the HTML markup not being rendered; instead it is displayed as text in the Salesforce user interface.

Be cautious if you specify false for the escape argument. Unescaped strings displayed in the Salesforce user interface can represent a vulnerability in the system because these strings might contain harmful code. If you want to include HTML markup in the error message, call this method with a false escape argument and make sure you escape any dynamic content, such as input field values. Otherwise, specify true for the escape argument or call field.addError(String errorMsg) instead.

Warning

clear()

Clears all field values

Signature

public Void clear()

Return Value

Type: Void

clone(Boolean, Boolean, Boolean, Boolean)

Creates a copy of the sObject record.

Signature

public sObject clone(Boolean opt_preserve_id, Boolean opt_IsDeepClone, Boolean opt_preserve_readonly_timestamps, Boolean opt_preserve_autonumber)

Parameters

opt_preserve_id
Type: Boolean
(Optional) Determines whether the ID of the original object is preserved or cleared in the duplicate. If set to true, the ID is copied to the duplicate. The default is false, that is, the ID is cleared.
opt_IsDeepClone
Type: Boolean
(Optional) Determines whether the method creates a full copy of the sObject field, or just a reference:
  • If set to true, the method creates a full copy of the sObject. All fields on the sObject are duplicated in memory, including relationship fields. Consequently, if you make changes to a field on the cloned sObject, the original sObject is not affected.
  • If set to false, the method performs a shallow copy of the sObject fields. All copied relationship fields reference the original sObjects. Consequently, if you make changes to a relationship field on the cloned sObject, the corresponding field on the original sObject is also affected, and vice-versa. The default is false.
opt_preserve_readonly_timestamps
Type: Boolean
(Optional) Determines whether the read-only timestamp fields are preserved or cleared in the duplicate. If set to true, the read-only fields CreatedById, CreatedDate, LastModifiedById, and LastModifiedDate are copied to the duplicate. The default is false, that is, the values are cleared.
opt_preserve_autonumber
Type: Boolean
(Optional) Determines whether auto number fields of the original object are preserved or cleared in the duplicate. If set to true, auto number fields are copied to the cloned object. The default is false, that is, auto number fields are cleared.

Return Value

Type: sObject (of same type)

Usage

For Apex saved using Salesforce.comAPI version 22.0 or earlier, the default value for the opt_preserve_id argument is true, that is, the ID is preserved.

Note

get(String)

Returns the value for the field specified by fieldName, such as AccountNumber.

Signature

public Object get(String fieldName)

Parameters

fieldName
Type: String

Return Value

Type: Object

Usage

For more information, see Dynamic SOQL.

get(Schema.sObjectField)

Returns the value for the field specified by the field token Schema.sObjectField, such as, Schema.Account.AccountNumber.

Signature

public Object get(Schema.sObjectField field)

Parameters

field
Type: Schema.SObjectField

Return Value

Type: Object

Usage

For more information, see Dynamic SOQL.

getOptions()

Returns the database.DMLOptions object for the sObject.

Signature

public Database.DMLOptions getOptions()

Return Value

Type: Database.DMLOptions

getSObject(String)

Returns the value for the specified field. This method is primarily used with dynamic DML to access values for external IDs.

Signature

public sObject getSObject(String fieldName)

Parameters

fieldName
Type: String

Return Value

Type: sObject

getSObject(Schema.SObjectField)

Returns the value for the field specified by the field token Schema.fieldName, such as, Schema.MyObj.MyExternalId. This method is primarily used with dynamic DML to access values for external IDs.

Signature

public sObject getSObject(Schema.SObjectField fieldName)

Parameters

fieldName
Type: Schema.SObjectField

Return Value

Type: sObject

getSObjects(String)

Returns the values for the specified field. This method is primarily used with dynamic DML to access values for associated objects, such as child relationships.

Signature

public sObject[] getSObjects(String fieldName)

Parameters

fieldName
Type: String

Return Value

Type: sObject[]

Usage

For more information, see Dynamic DML.

getSObjects(Schema.SObjectType)

Returns the value for the field specified by the field token Schema.fieldName, such as, Schema.Account.Contact. This method is primarily used with dynamic DML to access values for associated objects, such as child relationships.

Signature

public sObject[] getSObjects(Schema.SObjectType fieldName)

Parameters

fieldName
Type: Schema.SObjectType

Return Value

Type: sObject[]

getSObjectType()

Returns the token for this sObject. This method is primarily used with describe information.

Signature

public Schema.SObjectType getSObjectType()

Return Value

Type: Schema.SObjectType

Usage

For more information, see Understanding Apex Describe Information.

getQuickActionName()

Retrieves the name of a publisher action associated with this sObject. Typically used in triggers.

Signature

public String getQuickActionName()

Return Value

Type: String

put(String, Object)

Sets the value for the specified field and returns the previous value for the field.

Signature

public Object put(String fieldName, Object value)

Parameters

fieldName
Type: String
value
Type: Object

Return Value

Type: Object

put(Schema.SObjectField, Object)

Sets the value for the field specified by the field token Schema.sObjectField, such as, Schema.Account.AccountNumber and returns the previous value for the field.

Signature

public Object put(Schema.SObjectField fieldName, Object value)

Parameters

fieldName
Type: Schema.SObjectField
value
Type: Object

Return Value

Type: Object

putSObject(String, sObject)

Sets the value for the specified field. This method is primarily used with dynamic DML for setting external IDs. The method returns the previous value of the field.

Signature

public sObject putSObject(String fieldName, sObject value)

Parameters

fieldName
Type: String
value
Type: sObject

Return Value

Type: sObject

putSObject(Schema.sObjectType, sObject)

Sets the value for the field specified by the token Schema.sObjectType. This method is primarily used with dynamic DML for setting external IDs. The method returns the previous value of the field.

Signature

public sObject putSObject(Schema.sObjectType fieldName, sObject value)

Parameters

fieldName
Type: Schema.SObjectType
value
Type: sObject

Return Value

Type: sObject

setOptions(Database.DMLOptions)

Sets the DMLOptions object for the sObject.

Signature

public Void setOptions(database.DMLOptions DMLOptions)

Parameters

DMLOptions
Type: Database.DMLOptions

Return Value

Type: Void