Usage of nsITransaction Interface

 Gets an undo-able transaction for removing a folder from the bookmarks
 tree. 
  @param folder
         The id of the folder to remove.
  @return An object implementing nsITransaction that can be used to undo 
          or redo the action. 

 This method exists because complex delete->undo operations rely on 
 recreated folders to have the same ID they had before they were deleted, 
 so that any other items deleted in different transactions can be 
 re-inserted correctly. This provides a safe encapsulation of this 
 functionality without exposing the ability to recreate folders with 
 specific IDs (potentially dangerous if abused by other code!) in the
 public API.

nsITransaction getRemoveFolderTransaction(in long long aFolder)

 Transaction for performing several Places Transactions in a single batch. 
 
 @param aName
        title of the aggregate transactions
 @param aTransactions
        an array of transactions to perform
 @returns nsITransaction object

nsITransaction aggregateTransactions(in AString aName, in nsIVariant aTransactions)

 Transaction for creating a new folder item.

 @param aName
        the name of the new folder
 @param aContainerId
        the identifier of the folder in which the new folder should be
        added.
 @param [optional] aIndex
        the index of the item in aContainer, pass -1 or nothing to create
        the item at the end of aContainer.
 @param [optional] aAnnotations
        the annotations to set for the new folder.
 @param [optional] aChildItemsTransactions
        array of transactions for items to be created under the new folder.
 @returns nsITransaction object

nsITransaction createFolder(in AString aName, in long long aContainerId, [optional] in long long aIndex, [optional] in nsIVariant aAnnotations, [optional] in nsIVariant aChildItemsTransactions)

 Transaction for creating a new bookmark item

 @param aURI
        the uri of the new bookmark (nsIURI)
 @param aContainerId
        the identifier of the folder in which the bookmark should be added.
 @param [optional] aIndex
        the index of the item in aContainer, pass -1 or nothing to create
        the item at the end of aContainer.
 @param [optional] aTitle
        the title of the new bookmark.
 @param [optional] aKeyword
        the keyword of the new bookmark.
 @param [optional] aAnnotations
        the annotations to set for the new bookmark.
 @param [optional] aChildTransactions
        child transactions to commit after creating the bookmark. Prefer
        using any of the arguments above if possible. In general, a child
        transations should be used only if the change it does has to be
        reverted manually when removing the bookmark item.
        a child transaction must support setting its bookmark-item
        identifier via an "id" js setter.
 @returns nsITransaction object

nsITransaction createItem(in nsIURI aURI, in long long aContainerId, [optional] in long long aIndex, [optional] in AString aTitle, [optional] in AString aKeyword, [optional] in nsIVariant aAnnotations, [optional] in nsIVariant aChildTransactions)

 Transaction for creating a new live-bookmark item.

 @see nsILivemarksService::createLivemark for documentation regarding the
 first three arguments.

 @param aContainerId
        the identifier of the folder in which the live-bookmark should be
        added.
 @param [optional]  aIndex
        the index of the item in aContainer, pass -1 or nothing to create
        the item at the end of aContainer.
 @param [optional] aAnnotations
        the annotations to set for the new live-bookmark.
 @returns nsITransaction object

nsITransaction createLivemark(in nsIURI aFeedURI, in nsIURI aSiteURI, in AString aName, in long long aContainerId, [optional] in long long aIndex, [optional] in nsIVariant aAnnotations)

 Transaction for creating a new separator item

 @param aContainerId
        the identifier of the folder in which the separator should be
        added.
 @param [optional] aIndex
        the index of the item in aContainer, pass -1 or nothing to create
        the separator at the end of aContainer.
 @returns nsITransaction object

nsITransaction createSeparator(in long long aContainerId, [optional] in long long aIndex)

 Transaction for editing a bookmark's keyword.

 @param aBookmarkId
        id of the bookmark to edit
 @param aNewKeyword
        new keyword for the bookmark
 @returns nsITransaction object

nsITransaction editBookmarkKeyword(in long long aBookmarkId, in AString aNewKeyword)

 Transaction for editing a bookmark's microsummary.

 @param aBookmarkId
        id of the bookmark to edit
 @param aNewMicrosummary
        new microsummary for the bookmark
 @returns nsITransaction object

nsITransaction editBookmarkMicrosummary(in long long aBookmarkId, in nsIMicrosummary aNewMicrosummary)

 Transaction for editing the post data associated with a bookmark.

 @param aBookmarkId
        id of the bookmark to edit
 @param aPostData
        post data
 @returns nsITransaction object

nsITransaction editBookmarkPostData(in long long aBookmarkId, in AString aPostData)

 Transaction for editing a bookmark's uri.

 @param aBookmarkId
        id of the bookmark to edit
 @param aNewURI
        new uri for the bookmark
 @returns nsITransaction object

nsITransaction editBookmarkURI(in long long aBookmarkId, in nsIURI aNewURI)

 Transaction for editing an item's date added property.

 @param aItemId
        id of the item to edit
 @param aNewDateAdded
        new date added for the item 
 @returns nsITransaction object

nsITransaction editItemDateAdded(in long long aItemId, in PRTime aNewDateAdded)

 Transaction for editing a the description of a bookmark or a folder
 
 @param aItemId
        id of the item to edit
 @param aDescription
        new description
 @returns nsITransaction object

nsITransaction editItemDescription(in long long aItemId, in AString aDescription)

 Transaction for editing an item's last modified time.

 @param aItemId
        id of the item to edit
 @param aNewLastModified
        new last modified date for the item 
 @returns nsITransaction object

nsITransaction editItemLastModified(in long long aItemId, in PRTime aNewLastModified)

 Transaction for editting a bookmark's title.

 @param aItemId
        id of the item to edit
 @param aNewTitle
        new title for the item to edit
 @returns nsITransaction object

nsITransaction editItemTitle(in long long aItemId, in AString aNewTitle)

 Transaction for editting a live bookmark's feed URI.

 @param aLivemarkId
        id of the livemark
 @param aURI
        new feed uri
 @returns nsITransaction object

nsITransaction editLivemarkFeedURI(in long long aLivemarkId, in nsIURI aURI)

 Transaction for editing a live bookmark's site URI.

 @param aLivemarkId
        id of the livemark
 @param aURI
        new site uri
 @returns nsITransaction object

nsITransaction editLivemarkSiteURI(in long long aLivemarkId, in nsIURI aURI)

 Transaction for moving an Item.

 @param aItemId
        the id of the item to move
 @param aNewContainerId
        id of the new container to move to
 @param aNewIndex
        index of the new position to move to
 @returns nsITransaction object

nsITransaction moveItem(in long long aItemId, in long long aNewContainerId, in long long aNewIndex)

 Transaction for removing an Item

 @param aItemId
        id of the item to remove
 @returns nsITransaction object

nsITransaction removeItem(in long long aItemId)

 Transaction for setting/unsetting an item annotation

 @param aItemId
        id of the item where to set annotation
 @param aAnnotationObject
        Object representing an annotation, containing the following
        properties: name, flags, expires, type, mimeType (only used for
        binary annotations), value.
        If value is null the annotation will be removed
 @returns nsITransaction object

nsITransaction setItemAnnotation(in nsIVariant aItemId, in nsIVariant aAnnotationObject)

 Transaction for setting/unsetting Load-in-sidebar annotation

 @param aBookmarkId
        id of the bookmark where to set Load-in-sidebar annotation
 @param aLoadInSidebar
        boolean value
 @returns nsITransaction object

nsITransaction setLoadInSidebar(in long long aBookmarkId, in boolean aLoadInSidebar)

 Transaction for setting/unsetting a page annotation

 @param aURI
        URI of the page where to set annotation
 @param aAnnotationObject
        Object representing an annotation, containing the following
        properties: name, flags, expires, type, mimeType (only used for
        binary annotations), value.
        If value is null the annotation will be removed
 @returns nsITransaction object

nsITransaction setPageAnnotation(in nsIURI aURI, in nsIVariant aAnnotationObject)

 Transaction for sorting a folder by name

 @param aFolderId
        id of the folder to sort
 @returns nsITransaction object

nsITransaction sortFolderByName(in long long aFolderId)

 Transaction for tagging a URL with the given set of tags. Current tags set
 for the URL persist. It's the caller's job to check whether or not aURI
 was already tagged by any of the tags in aTags, undoing this tags
 transaction removes them all from aURL!

 @param aURI
        the URL to tag.
 @param aTags
        Array of tags to set for the given URL.

nsITransaction tagURI(in nsIURI aURI, in nsIVariant aTags)

 Transaction for removing tags from a URL. It's the caller's job to check
 whether or not aURI isn't tagged by any of the tags in aTags, undoing this
 tags transaction adds them all to aURL!

 @param aURI
        the URL to un-tag.
 @param aTags
        Array of tags to unset. pass null to remove all tags from the given
        url.

nsITransaction untagURI(in nsIURI aURI, in nsIVariant aTags)

 getItem() returns the transaction at the given index in the list. Note that
 a null can be returned here if the item is a batch. The transaction
 returned is AddRef'd so it is up to the caller to Release the transaction
 when it is done.
 @param aIndex The index of the item in the list.

nsITransaction getItem(in long aIndex)

 Returns an AddRef'd pointer to the transaction at the top of the
 redo stack. Callers should be aware that this method could return
 return a null in some implementations if there is a batch at the top
 of the redo stack.

nsITransaction peekRedoStack()

 Returns an AddRef'd pointer to the transaction at the top of the
 undo stack. Callers should be aware that this method could return
 return a null in some implementations if there is a batch at the top
 of the undo stack.

nsITransaction peekUndoStack()

 doTransaction() fires a transaction.
 It is provided here so clients can create their own transactions.
 If a transaction manager is present, it is used.  
 Otherwise, the transaction is just executed directly.

 @param aTxn the transaction to execute

void doTransaction(in nsITransaction txn)

 Attempts to merge a transaction into "this" transaction. Both transactions
 must be in their undo state, doTransaction() methods already called. The
 transaction manager calls this method to coalesce a new transaction with
 the transaction on the top of the undo stack.
 This method returns a boolean value that indicates the merge result.
 A true value indicates that the transactions were merged successfully,
 a false value if the merge was not possible or failed. If true,
 the transaction manager will Release() the new transacton instead of
 pushing it on the undo stack.
 @param aTransaction the previously executed transaction to merge.

boolean merge(in nsITransaction aTransaction)

 Called after a transaction manager tries to merge
 a transaction, that was just executed, with the
 transaction at the top of the undo stack.
 @param aManager the transaction manager ending a batch.
 @param aTopTransaction the transaction at the top of the undo stack.
 @param aTransactionToMerge the transaction to merge.
 @param aDidMerge true if transaction was merged, else false.
 @param aMergeResult the nsresult returned after the merge attempt.
 @param aInterrupt listeners should set this to PR_TRUE if they
 want to interrupt normal control flow, without throwing an error.

void didMerge(in nsITransactionManager aManager, in nsITransaction aTopTransaction, in nsITransaction aTransactionToMerge, in boolean aDidMerge, in nsresult aMergeResult)

 Called before a transaction manager tries to merge
 a transaction, that was just executed, with the
 transaction at the top of the undo stack.
 @param aManager the transaction manager ending a batch.
 @param aTopTransaction the transaction at the top of the undo stack.
 @param aTransactionToMerge the transaction to merge.
 @result boolean value returned by listener which indicates
 it's desire to interrupt normal control flow. Listeners should
 return true if they want to interrupt normal control flow, without
 throwing an error. Note that listeners can also interrupt normal
 control flow by throwing an nsresult that indicates an error.

boolean willMerge(in nsITransactionManager aManager, in nsITransaction aTopTransaction, in nsITransaction aTransactionToMerge)

 Called after a transaction manager calls the doTransaction() method of
 a transaction.
 @param aManager the transaction manager that did the transaction.
 @param aTransaction the transaction that was executed.
 @param aDoResult the nsresult returned after executing
 the transaction.

void didDo(in nsITransactionManager aManager, in nsITransaction aTransaction, in nsresult aDoResult)

 Called after a transaction manager calls the Redo() method of
 a transaction.
 @param aManager the transaction manager redoing the transaction.
 @param aTransaction the transaction being redone.
 @param aRedoResult the nsresult returned after redoing the transaction.

void didRedo(in nsITransactionManager aManager, in nsITransaction aTransaction, in nsresult aRedoResult)

 Called after a transaction manager calls the Undo() method of
 a transaction.
 @param aManager the transaction manager undoing the transaction.
 @param aTransaction the transaction being undone.
 @param aUndoResult the nsresult returned after undoing the transaction.

void didUndo(in nsITransactionManager aManager, in nsITransaction aTransaction, in nsresult aUndoResult)

 Called before a transaction manager calls a transaction's
 doTransaction() method.
 @param aManager the transaction manager doing the transaction.
 @param aTransaction the transaction being executed.
 @result boolean value returned by listener which indicates
 it's desire to interrupt normal control flow. Listeners should
 return true if they want to interrupt normal control flow, without
 throwing an error.

boolean willDo(in nsITransactionManager aManager, in nsITransaction aTransaction)

 Called before a transaction manager calls the Redo() method of
 a transaction.
 @param aManager the transaction manager redoing the transaction.
 @param aTransaction the transaction being redone.
 @result boolean value returned by listener which indicates
 it's desire to interrupt normal control flow. Listeners should
 return true if they want to interrupt normal control flow, without
 throwing an error. Note that listeners can also interrupt normal
 control flow by throwing an nsresult that indicates an error.

boolean willRedo(in nsITransactionManager aManager, in nsITransaction aTransaction)

 Called before a transaction manager calls the Undo() method of
 a transaction.
 @param aManager the transaction manager undoing the transaction.
 @param aTransaction the transaction being undone.
 @result boolean value returned by listener which indicates
 it's desire to interrupt normal control flow. Listeners should
 return true if they want to interrupt normal control flow, without
 throwing an error. Note that listeners can also interrupt normal
 control flow by throwing an nsresult that indicates an error.

boolean willUndo(in nsITransactionManager aManager, in nsITransaction aTransaction)

 Called after a transaction manager tries to merge
 a transaction, that was just executed, with the
 transaction at the top of the undo stack.
 @param aManager the transaction manager ending a batch.
 @param aTopTransaction the transaction at the top of the undo stack.
 @param aTransactionToMerge the transaction to merge.
 @param aDidMerge true if transaction was merged, else false.
 @param aMergeResult the nsresult returned after the merge attempt.
 @param aInterrupt listeners should set this to PR_TRUE if they
 want to interrupt normal control flow, without throwing an error.

void didMerge(in nsITransactionManager aManager, in nsITransaction aTopTransaction, in nsITransaction aTransactionToMerge, in boolean aDidMerge, in nsresult aMergeResult)

 Called before a transaction manager tries to merge
 a transaction, that was just executed, with the
 transaction at the top of the undo stack.
 @param aManager the transaction manager ending a batch.
 @param aTopTransaction the transaction at the top of the undo stack.
 @param aTransactionToMerge the transaction to merge.
 @result boolean value returned by listener which indicates
 it's desire to interrupt normal control flow. Listeners should
 return true if they want to interrupt normal control flow, without
 throwing an error. Note that listeners can also interrupt normal
 control flow by throwing an nsresult that indicates an error.

boolean willMerge(in nsITransactionManager aManager, in nsITransaction aTopTransaction, in nsITransaction aTransactionToMerge)

 The nsITransactionManager interface.
 <P>
 This interface is implemented by an object that wants to
 manage/track transactions.


 Calls a transaction's doTransaction() method, then pushes it on the
 undo stack.
 <P>
 This method calls the transaction's AddRef() method.
 The transaction's Release() method will be called when the undo or redo
 stack is pruned or when the transaction manager is destroyed.
 @param aTransaction the transaction to do.

void doTransaction(in nsITransaction aTransaction)