COEditingContext class documentation
COEditingContext : NSObject <COPersistentObjectContext>Overview
Its functionality is split across 5 main classes (there is a owner chain where each element owns the one just below in the list):
- COEditingContext
- Entry point for opening and creating stores. Handles persistent root insertion and deletion
- COPersistentRoot
- Versioned sandbox of inner objects, with a history graph (CORevision), and one or more branches (COBranch).
- COBranch
- A position on the history graph, with the revision contents exposed as a COObjectGraphContext
- COObjectGraphContext
- manages COObject graph, tracks changes and handles reloading new states
- COObject
- Mutable inner object
CORevision also fits this set although it is not directly owned by one object.
Common Use Cases
Typically COEditingContext is used at application startup to create or open a store (+contextWithURL:), when creating, deleting or accessing persistent roots, and to track and commit changes in all persistent roots.
To create, delete or access persistent roots, see Creation and Deletion sections in COPersistentRoot documentation.
Metamodel
For all the persistent root inner objects, a valid entity description must exist in -[COEditingContext modelDescriptionRepository] .
The metamodel in the model description repository is passed downwards from the editing context to the object graph contexts that manages the inner objects (see -[COObjectGraphContext modelDescriptionRepository] )
To register a new entity description that describe a COObject subclass, override +[NSObject newEntityDescription] , and ETModelDescriptionRepository will automatically register it on launch in +[ETModelDescriptionRepository mainRepository] (the default repository used by +contextWithURL:).
To register a new entity description without writing a COObject subclass, see ETModelDescriptionRepository documentation. To instantiate the correct inner objects or entities, those can be passed to -[COObject initWithEntityDescription:objectGraphContext:] , as -insertNewPersistentRootWithEntityName: does. For more details about inner object initialization, see COObject.
Change Tracking
COEditingContext, COPersistentRoot, COBranch, and COObjectGraphContext tracks the uncommitted or pending changes in their persistent properties, and in their owned element among the 5 core classes (see the ownership list at the beginning of the overview).
For the editing context, -hasChanges computes the current change tracking state based on its own changes and the changes in the persistent roots, -[COPersistentRoot hasChanges] is based on its own changes and the changes in the branches, and so on until reaching COObjectGraphContext. Take note that the same recursive model applies to -discardChanges .
Object Equality
COEditingContext, COPersistentRoot, COBranch, and COObjectGraphContext do not override -hash or -isEqual:, so instances of these classes are only considered equal to the same instances.
These classes form an in-memory view on a database, and the notion of two of these views being equal isn't useful or interesting.
Commits and Undo
In the current implementation, all changes made in a COEditingContext are committed atomically in one SQLite transaction. However, when you consider CoreObject as a version control system, atomicity only exists per-persistent root, since persistent roots are the units of versioning and each can be manipulated independently (rolled back, etc.).
For committing changes, see -commitWithIdentifier:metadata:undoTrack:error: and other similar commit methods. Take note that COCommitDescriptor provides support to localize the commit metadata.
For recording these commits as undoable actions, see COUndoTrack. CoreObject supports two undo/redo models that both conform to the COTrack protocol:- a branch undo/redo model, that moves the current revision pointer on the branch path (this model cannot undo/redo commits involving changes that don't create a new revision, or span several persistent roots or branches)
- a rich undo/redo model based on recording commits on an undo track (and even aggregating commits accross multiple undo tracks)
In most cases, to support undo/redo in an application, use a COUndoTrack. Branch undo/redo can be used to inspect and navigate a single persistent root history (e.g. in a timeline UI presenting a document history).
Creating a New Context
- + (COEditingContext *) contextWithURL: (NSURL *)aURL
Returns a new autoreleased context initialized with the store located at the given URL.
See also -initWithStore: and -[COSQLiteStore initWithURL:] .
- - (id) initWithStore: (COSQLiteStore *)store
Initializes a context which persists its content in the given store.
The model repository is set to -[ETModelDescription mainRepository] .
See also -initWithStore:modelDescriptionRepository:.
- - (id) initWithStore: (COSQLiteStore *)store modelDescriptionRepository: (ETModelDescriptionRepository *)aRepo
Initializes a context which persists its content in the given store, and manages it using the metamodel provided by the model description repository.
For a nil model repository, or a repository that doesn't a COObject entity description, raises a NSInvalidArgumentException.
- - (id) init
Initializes the context with no store. As a result, the context content is not persisted.
See also -initWithStore: .
Accessing All Persistent Roots
- - (NSSet *) persistentRoots
Returns all persistent roots in the store (excluding those that are marked as deleted on disk), plus those pending insertion and undeletion (and minus those pending deletion).
- - (NSSet *) deletedPersistentRoots
Returns persistent roots marked as deleted on disk, excluding those that are pending undeletion, plus those pending deletion.
Store and Metamodel Access
- - (ETModelDescriptionRepository *) modelDescriptionRepository
Returns the model description repository, which holds the metamodel that describes all the persistent objects editable in the context.
Managing Persistent Roots
- - (COPersistentRoot *) persistentRootForUUID: (ETUUID *)aUUID
Returns the persistent root bound the the given UUID in the store or nil.
The editing context retains the returned persistent root.
This method can return any persistent roots among -persistentRoots and -deletedPersistentRoots (including those pending deletion and undeletion), but the loading is restricted to the requested persistent root.
- - (COPersistentRoot *) insertNewPersistentRootWithRootObject: (COObject *)aRootObject
Returns a new persistent root that uses the given root object.
The returned persistent root is added to -persistentRootsPendingInsertion and will be saved to the store on the next commit.
The object graph context of the root object must be transient, otherwise a NSInvalidArgumentException is raised.
The object graph context of the root object must also use the same model description repository than the receiver, otherwise a NSInvalidArgumentException is raised.
For a nil root object, raises a NSInvalidArgumentException.
- - (COPersistentRoot *) insertNewPersistentRootWithEntityName: (NSString *)anEntityName
Creates a root object of the requested entity and returns a new persistent root using that root object.
Pending Changes
- - (NSSet *) persistentRootsPendingInsertion
The new persistent roots to be saved in the store on the next commit.
- - (NSSet *) persistentRootsPendingDeletion
The persistent roots to be deleted in the store on the next commit.
- - (NSSet *) persistentRootsPendingUndeletion
The persistent roots to be undeleted in the store on the next commit.
- - (NSSet *) persistentRootsPendingUpdate
The persistent roots to be updated in the store on the next commit.
- - (BOOL) hasChanges
Returns whether the context contains uncommitted changes.
Persistent root insertions, deletions, undeletions, and modifications (e.g., changing main branch, deleting branches, adding branches, editing branch metadata, reverting branch to a past revision) all count as uncommitted changes.
See also -discardAllChanges and -[COPersistentRoot hasChanges] .
- - (void) discardAllChanges
Discards the uncommitted changes to reset the context to its last commit state.
Persistent root insertions, deletions, undeletions and modifications (e.g., changing main branch, deleting branches, adding branches, editing branch metadata, reverting branch to a past revision) will be cancelled.
All uncommitted inner object edits in child persistent roots will be cancelled.
-persistentRootsPendingInsertion, -persistentRootsPendingDeletion, -persistentRootsPendingUndeletion and -persistentRootsPendingUpdate will all return empty sets once the changes have been discarded.
See also -hasChanges and -[COPersistentRoot discardAllChanges] .
Committing Changes
- - (BOOL) commitWithIdentifier: (NSString *)aCommitDescriptorId undoTrack: (COUndoTrack *)undoTrack error: (COError **)anError
Commits the current changes to the store bound to a commit descriptor identifier, and returns whether it succeeds.
See -commitWithIdentitifer:metadata:undoTrack:error.
- - (BOOL) commitWithIdentifier: (NSString *)aCommitDescriptorId metadata: (NSDictionary *)additionalMetadata undoTrack: (COUndoTrack *)undoTrack error: (COError **)anError
Commits the current changes to the store, bound to a commit descriptor identifier along the additional metadatas, and returns whether it succeeds.
The metadata dictionary must be a valid property list or nil, otherwise a serialization exception is raised.
The changed objects are validated with -[COObject validate] , and an aggregate validation error per object is returned in [anError errors]. For each aggregate validation error, -[COError errors] will return validation suberrors. For example, [[[anError errors] firstObject] errors] mappedCollection] validationResult] returns validation issues that pertain to the first validated object.
If the method returns NO, the error argument is set, otherwise it is nil.
One or more undo tracks can be passed to record the commit as a command.
For programs exposing the history to an end user, you must use this method that supports history localization through COCommitDescriptor and not -commitWithMetadata:undoTrack:error:.
See COCommitDescriptor to understand how the localization works.
- - (BOOL) commitWithMetadata: (NSDictionary *)metadata undoTrack: (COUndoTrack *)undoTrack error: (COError **)anError
Commits the current changes to the store along the metadatas and returns whether it succeeds.
The metadata dictionary must be a valid JSON object or nil, otherwise a serialization exception is raised.
If the method returns NO, the error argument is set, otherwise it is nil.
One or more undo tracks can be passed to record the commit as a command.
For programs exposing the history to an end user, you must not use this method, but -commitWithIdentifier:metadata:undoTrack:error: or -commitWithIdentifier:undoTrack:error: that both support history localization through COCommitDescriptor.
- - (BOOL) commit
Commits the current changes to the store and returns whether it succeeds.
You should avoid using this method in release code, it is mainly useful for debugging and quick development.
See also -commitWithMetadata:undoTrack:error:.
- - (BOOL) commitWithUndoTrack: (COUndoTrack *)aTrack
Commits the current changes to the store, records them on the undo track and returns whether it succeeds. You should avoid using this method in release code, it is mainly useful for debugging and quick development.
See also -commitWithMetadata:undoTrack:error:.
Description
- - (NSString *) detailedDescription
Returns a multi-line description including informations about the pending changes.
Deprecated
- - (COEditingContext *) editingContext
Returns self.
See also -[COPersistentObjectContext editingContext] .
