Sharing Objects
Every custom object, except Detail objects in a Master-Detail relationship, has a corresponding sharing object to store its record-level sharing rules. The sharing object is created automatically by Force.com and is invisible to the native user interface. It can be seen in the Force.com IDE’s Schema Explorer. Its name is the name of your object with __Share appended. For example, the sharing object for the Project__c object is Project__Share.
The sharing object contains explicit sharing rules. These are created by Force.com managed sharing, user managed sharing, and Apex managed sharing. It does not contain implicit shares such as organization-wide defaults.
Four fields of the sharing object control how records are shared between users and groups, as follows:
ParentID—ParentId is the unique identifier of the record being shared.
UserOrGroupId—This is the unique identifier of the user or group that the sharing rule is granting access to. Groups are public groups or roles.
AccessLevel—This field stores the level of access granted to the user or group for this record. The three valid values are Read (Read Only), Edit (Read and Edit), and All (Full Control). Apex managed sharing cannot set a record to All. The value of AccessLevel must be more permissive than the organization-wide default or a runtime exception is thrown.
RowCause—The purpose of the RowCause field is to track the origin of the sharing rule. Valid values are Manual (the default) or a custom sharing reason, defined on the object in the Apex Sharing Reasons related list. Manual sharing rules can be edited and removed by the record owner and are reset when record ownership changes. Sharing records with a custom reason are not reset when ownership changes and cannot be edited or removed without the administrative permission Modify All Data.
Restrictions
Two important restrictions exist on Apex managed sharing:
Objects with an organization-wide default sharing level of Public Read/Write, the most permissive setting, cannot use Apex managed sharing. Set the level to Private or Public Read Only instead.
After a sharing record is created, the only field that can be updated is the access level. If you need to change other fields, delete the sharing record entirely and re-create it.
Caution
When the organization-wide sharing default is changed for an object, all sharing rules are recalculated. This causes your Apex managed sharing rules to be deleted. To re-create them, you must implement an Apex class to participate in the recalculation event. This code uses the Apex batch processing feature to allow processing of millions of records in smaller groups of records, to stay within governor limits. The Apex batch processing functionality is covered in Chapter 9, “Batch Processing.”