You can update objects persisted in an object store using a batch operation. After performing an action on an object (such as, checkin, or delete), you add the object to an UpdatingBatch instance; this in contrast to individual (non-batched) operations on objects, when you would normally save the object to execute the pending update to the object. When you have added to the UpdatingBatch instance all objects to be updated, you eventually call the updateBatch method on the instance to execute the pending batch update.
This is a transactional operation: all calls in the batch succeed or fail as a unit. In the event of a failure, the transaction is rolled back and an exception is thrown.
The general sequence for performing a batch update operation is as follows:
Java™ Example
// Get an instance of the UpdatingBatch class.
Domain myDomain = os.get_Domain();
// The RefreshMode parameter is set to REFRESH to indicate that the property cache for
// this instance is to be refreshed with the updated data.
UpdatingBatch ub = UpdatingBatch.createUpdatingBatchInstance(myDomain, RefreshMode.REFRESH);
// Add object updates to the batch.
// Assume, in this case, that these documents have already been checked out.
// No property filters are used (filter parameters are null).
Document doc1 = Factory.Document.fetchInstance(os, new Id("{F905DBD6-5A69-4252-9985-2D3DD28D7FBA}"), null);
Document doc2 = Factory.Document.fetchInstance(os, new Id("{35026B90-B443-40CA-B5C3-66BEAD13E2B7}"), null);
// First update to be included in batch.
doc1 = (Document) doc1.get_Reservation();
doc1.checkin(null, CheckinType.MAJOR_VERSION);
// Second update to be included in batch.
doc2 = (Document) doc2.get_Reservation();
doc2.checkin(null, CheckinType.MAJOR_VERSION);
// Third update to be included in batch. Sets the document title and assigns the
// specified property values (Properties.putValue) to the retrieved properties for the
// doc (the inherited EngineObject.getProperties).
doc1.getProperties().putValue("DocumentTitle", "doc1");
// Fourth update to be included in batch.
doc2.getProperties().putValue("DocumentTitle", "doc2");
// Adds all four updates (to the two Document objects) to the UpdatingBatch instance.
ub.add(doc1, null);
ub.add(doc2, null);
// Execute the batch update operation.
ub.updateBatch();
C# Example
// Get an instance of the UpdatingBatch class.
IDomain myDomain = os.Domain;
// The RefreshMode parameter is set to REFRESH to indicate that the property cache for
// this instance is to be refreshed with the updated data.
UpdatingBatch ub = UpdatingBatch.CreateUpdatingBatchInstance(myDomain, FileNet.Api.Constants.RefreshMode.REFRESH);
// Add object updates to the batch.
// Assume, in this case, that these documents have already been checked out.
// No property filters are used (filter parameters are null).
IDocument doc1 = Factory.Document.FetchInstance(os, new Id("{CF0BE923-DCFD-4832-8CE0-001E4A111E25}"), null);
IDocument doc2 = Factory.Document.FetchInstance(os, new Id("{A25A8FB0-D4EF-4690-83BB-41F7EB98D631}"), null);
// First update to be included in batch.
doc1 = (IDocument) doc1.Reservation;
doc1.Checkin(AutoClassify.DO_NOT_AUTO_CLASSIFY, CheckinType.MAJOR_VERSION);
// Second update to be included in batch.
doc2 = (IDocument) doc2.Reservation;
doc2.Checkin(AutoClassify.DO_NOT_AUTO_CLASSIFY, CheckinType.MAJOR_VERSION);
// Third update to be included in batch. Sets the document title and assigns the
// specified property values (Properties.putValue) to the retrieved properties for the
// doc (the inherited EngineObject.getProperties).
doc1.Properties.GetProperty("DocumentTitle").SetObjectValue("doc1");
// Fourth update to be included in batch.
doc2.Properties.GetProperty("DocumentTitle").SetObjectValue("doc2");
// Adds all four updates (to the two Document objects) to the UpdatingBatch instance.
ub.Add(doc1, null);
ub.Add(doc2, null);
// Execute the batch update operation.
ub.UpdateBatch();
Example: Batch Update to Delete Objects
The following example illustrates a batch update operation to delete objects:
Java Example
public static void updatePendingDeletion(Domain myDomain) throws Exception
{
PropertyFilter myOSFilter = null;
String myOS = "LaurelTree";
ObjectStore os = Factory.ObjectStore.fetchInstance(myDomain, myOS, myOSFilter);
// The RefreshMode parameter indicates that the property cache for this instance is to be
// refreshed with the updated data.
UpdatingBatch ub = UpdatingBatch.createUpdatingBatchInstance(myDomain, RefreshMode.NO_REFRESH);
// Get the documents. Calls findDocs routine below to get up to three documents in the
// specified object store having a DocumentTitle of "Batch Deleting Example". These
// documents might or might not be currently checked out.
Document[] docArr = findDocs(os, "Batch Deleting Example", false, 3);
Document doc1 = docArr[0];
Document doc2 = docArr[1];
Document doc3 = docArr[2];
// Override update sequence number check.
doc1.setUpdateSequenceNumber(null);
doc2.setUpdateSequenceNumber(null);
doc3.setUpdateSequenceNumber(null);
// The inherited IndependentlyPersistedObject.delete method adds this pending action.
doc1.delete();
doc2.delete();
doc3.delete();
// Adds the Document objects with pending deletions to the UpdatingBatch instance.
ub.add(doc1, null);
ub.add(doc2, null);
ub.add(doc3, null);
ub.updateBatch();
}
// Uses SearchSQL and SearchScope to find documents of the specified title, then fetches
// these Document objects. The onlyReservation parameter indicates whether or not you
// want only documents that are currently checked out.
static Document[] findDocs(
ObjectStore os,
String docTitle,
boolean onlyReservation,
int findCount) throws Exception
{
// Declare document array.
Document[] docArr = new Document[findCount];
// Build the SQL statement.
String sql = "select d.this from Document d " +
"where DocumentTitle = '" + docTitle + "'";
SearchSQL searchSQL = new SearchSQL();
searchSQL.setQueryString(sql);
SearchScope searchScope = new SearchScope(os);
IndependentObjectSet objectSet = searchScope.fetchObjects(searchSQL, null, null, null);
int count = 0;
Iterator iter = objectSet.iterator();
while (iter.hasNext() == true && count < findCount)
{
Document doc = (Document) iter.next();
doc.refresh();
boolean statusReservation = false;
if (doc.get_VersionStatus() == VersionStatus.RESERVATION)
{
statusReservation = true;
}
if (onlyReservation == false || statusReservation == true)
{
System.out.println("Document: " + doc.get_Id().toString());
docArr[count] = doc;
count++;
}
}
// Throw an exception if unable to find documents.
if (count < findCount)
{
String message = "Unable to find " + findCount + " ";
if (onlyReservation == true)
{
message = message + "reserved ";
}
message = message + " documents with title '" + docTitle + "'";
throw new Exception(message);
}
// Return document array.
return docArr;
}
C# Example
public static void UpdatePendingDeletion(IDomain myDomain)
{
PropertyFilter myOSFilter = null;
string myOS = "LaurelTree";
IObjectStore os = Factory.ObjectStore.FetchInstance(myDomain, myOS, myOSFilter);
UpdatingBatch ub = UpdatingBatch.CreateUpdatingBatchInstance(myDomain, RefreshMode.NO_REFRESH);
IDocument[] docArr = findDocs(os, "Batch Deleting Example", false, 3);
IDocument doc1 = docArr[0];
IDocument doc2 = docArr[1];
IDocument doc3 = docArr[2];
doc1.SetUpdateSequenceNumber(null);
doc2.SetUpdateSequenceNumber(null);
doc3.SetUpdateSequenceNumber(null);
doc1.Delete();
doc2.Delete();
doc3.Delete();
ub.Add(doc1, null);
ub.Add(doc2, null);
ub.Add(doc3, null);
ub.UpdateBatch();
}
static IDocument[] findDocs(IObjectStore os, string docTitle, bool onlyReservation, int findCount)
{
IDocument[] docArr = new IDocument[findCount];
string sql = "select d.this from Document d " +
"where DocumentTitle = '" + docTitle + "'";
SearchSQL searchSQL = new SearchSQL();
searchSQL.SetQueryString(sql);
SearchScope searchScope = new SearchScope(os);
IIndependentObjectSet objectSet = searchScope.FetchObjects(searchSQL, null, null, null);
int count = 0;
foreach (IDocument doc in objectSet)
{
if (count < findCount)
{
doc.Refresh();
bool statusReservation = false;
if (doc.VersionStatus == VersionStatus.RESERVATION)
{
statusReservation = true;
}
if (onlyReservation == false || statusReservation == true)
{
System.Console.WriteLine("Document: " + doc.Id.ToString());
docArr[count] = doc;
count++;
}
}
}
if (count < findCount)
{
string message = "Unable to find " + findCount + " ";
if (onlyReservation == true)
{
message = message + "reserved ";
}
message = message + " documents with title '" + docTitle + "'";
throw new System.Exception(message);
}
return docArr;
}
Pending Batch Updates
You can find out whether a batch operation has been executed (the updateBatch method has been called) by calling the UpdatingBatch.hasPendingExecute method.
You can retrieve from the Content Engine any object subclassed from IndependentObject using a batch retrieval operation. As opposed to batch updating, this is not a transactional operation. Each object retrieval succeeds or fails individually.
Any subsequent changes to the objects retrieved in the batch are done in place (only references to the objects in the batch are retrieved).
The general sequence for performing a batch retrieval operation is as follows:
Java Example
// Get an instance of the RetrievingBatch class.
Domain myDomain = os.get_Domain();
RetrievingBatch rb = RetrievingBatch.createRetrievingBatchInstance(myDomain);
// Add objects to the batch. New objects are used for the purposes here.
Document doc1 = Factory.Document.createInstance(os, null);
doc1.checkin(null, null);
doc1.save(RefreshMode.NO_REFRESH);
Document doc2 = Factory.Document.createInstance(os, null);
doc2.checkin(null, null);
doc2.save(RefreshMode.NO_REFRESH);
// No filtering is used.
rb.add(doc1, null);
rb.add(doc2, null);
// Execute the batch retrieval operation:
rb.RetrieveBatch();C# Example
// Get an instance of the RetrievingBatch class.
IDomain myDomain= os.Domain;
RetrievingBatch rb = RetrievingBatch.CreateRetrievingBatchInstance(myDomain);
// Add objects to the batch. New objects are used for the purposes here.
IDocument doc1 = Factory.Document.CreateInstance(os, null);
doc1.Checkin(AutoClassify.DO_NOT_AUTO_CLASSIFY, CheckinType.MAJOR_VERSION);
doc1.Save(RefreshMode.NO_REFRESH);
IDocument doc2 = Factory.Document.CreateInstance(os, null);
doc2.Checkin(AutoClassify.DO_NOT_AUTO_CLASSIFY, CheckinType.MAJOR_VERSION);
doc2.Save(RefreshMode.NO_REFRESH);
// No filtering is used.
rb.Add(doc1, null);
rb.Add(doc2, null);
rb.RetrieveBatch();Checking for Retrieval Exceptions
After executing a batch retrieval operation, you can find out whether any of the object retrievals generated an exception by calling the hasExceptions method to return a boolean value. However, if you want to be able to do something based on whether a particular object retrieval threw an exception, you need to get the collection of BatchItemHandle instances, and iterate over them to find out which object retrieval threw an exception. For example:
Java Example
Iterator iterator1 = rb.getBatchItemHandles(null).iterator();
while (iterator1.hasNext()) {
BatchItemHandle obj = (BatchItemHandle) iterator1.next();
if (obj.hasException())
{
// Displays the exception, for the purpose of brevity here.
EngineRuntimeException thrown = obj.getException();
System.out.println("Exception: " + thrown.getMessage());
}
} C# Example
foreach (IBatchItemHandle obj in rb.GetBatchItemHandles(null))
{
if (obj.HasException())
{
FileNet.Api.Exception.EngineRuntimeException thrown = obj.GetException();
System.Console.WriteLine("Exception: " + thrown.Message);
}
}