A Transaction Manager is an object which handles many of the details of performing web transactions.
. A Transaction Manager takes care of the details of performing a web transaction. Basically, you provide the Transaction Manager with a basic description of the transaction you want performed, and it performs the transaction for you.
Here's a typical Transaction Manager session:
Transaction Manager clients can use a Transaction Manager to perform web transactions. Here are a couple of possible scenarios:
You obtain a transaction manager by calling the Transaction Core method GetNewTransactionMgr();
transactionMgr := TransactionCore:GetNewTransactionMgr();
Once this method returns a Transaction Manager instance, that Transaction Manager is ready to perform transactios.
Note that this method may return NIL if there are not enough system resources available to support another Transaction Manager.
This method activates whatever Caches, Protocols and Converters are necessary to carry out the requested transaction and return a stream containing the desired content in the desired format. This method accepts a standard transaction request frame, along with a callback. When this method has completed successfully, your callback will be called with a stream which accesses the content requested.
TransactionMgr:GetWebContent(transactionRequest, cbContext, cbMethodSym);
This method obtains a stream to the content given by the transactionRequest frame. This method calls your callback with the following parameters:
This method calls your callback as follows:
AddDeferredSend(cbContext,cbMethodSym,[InputStream, Error]);
Note that once you've finished reading data from the InputStream, you should either Finalize or Reset the Transaction Manager.
This method independently handles a web transaction. It either reports back to you with a viewer for the given obtained type, or it spawns an independent Protocol or Data Handler to deal with the transaction. If it returns a viewer to you, it is your code's job to display that viewer to the user. If it spawns an external handler of some sort, your code should consider the transaction completed.
TransactionMgr:HandleWebTransaction(req, callback, callbackSym);
Here the reqFrame is a standard transaction request frame, but now it includes MIME type info as well.
This method calls your callback with a single frame:
The meaning of the slots is as follows:
You can use this method to cancel your outstanding transaction request.
TransactionManager:CancelTransaction();
Note that this method will not necessarily cause your transaction request callbacks to be called with an error code (probably -16005). After this method has completed, you should be able to reuse the same Transaction Manager for a new transaction if you call TransactionManager:Reset().
Note that it is pointless to call CancelTransaction after HandleWebTransaction or GetWebContent have completed; instead, call Reset or Finalize to clean up the Transaction Manager.
This method returns a handler object for the given content stream. This object could be a Data Viewer or a Data Handler (but never a Data Converter).
obj := TransactionManager:GetHandlerObjectForContent(content);
This method is useful for obtaining a final sink of data (a Data Viewer or a Data Handler).
The parameters to this method are:
content. A content specification frame as discussed in "GetCachedContentByTransaction" on page 29.
This method returns a frame:
The slots are as follows:
handlerObject. This is the object which can handle the content data. This may be Data Viewer or a Data Handler. Note that this object may actually be linked to one or more Data Converters which place the data in the correct format.
class. The class of the object returned. DataHandler or DataViewer, or NIL. If necessary, the Display Manager will find a converter to convert the raw input stream into the MIME data type required by the Data Viewer or Data Handler returned.
error. An error code or NIL.
Note that a Data Viewer returned by this method will have had its Instantiate method called. Note that a Data Handler returned this method will NOT have had its Instantiate method called.
Note that this method is really only useful if you already have a source stream of data for which you want to find a handler object. You must still clean up the Transaction Manager as appropriate when you're finished with the returned handler object.
You should call the Transaction Manager Reset method between web transactions.
TransactionManager:Reset();
After calling this method you should be able to perform a new web transaction.
You should call the Transaction Manager Finalize method to completely clean-up the Transaction Manager and all of its associated objects.
TransactionManager:Finalize();
Note that after calling this method you should not attempt to use the Transaction Manager instance for additional transactions.
This method allows you to inform the Transaction Manager instance that you're interested in receiving status updates as various parts of the transaction are completed.
TransactionManager:SetStatusCallback(cbContext, cbMethodSym);
Note that your callback will be called with the following parameters:
callerContext. This parameter is a reference to the object which is passing up transaction status. You can use this parameter to know when to close the status display, for instance.
statusFrame. This frame is similar to the "update frame" used to update a protoStatusTemplate. Typically you would fill out slots such as statusText to update the status display.
Note that most third-party code shouldn't need to use this method. It is used by the Document Container to display status to the user in NetHopper.
This method can be used to update the status of a transaction.
TransactionManager:SetTransactionStatus(self, statusFrame);
This method passes up status to any interested clients. Note that this method can also be called via inheritance from Protocols, Converters, Handlers, and Stashers.
The parameters to this method are:
self. Always pass your self context as the first parameter to this method.
statusFrame. See the SetStatusCallback method above for information about statusFrame
content := TransMgr:GetCachedContentByTransaction(transReqFrame, mimeType);
This method returns a content specification frame with the following format:
The slots are defined as follows:
type. Either 'cacheObject or 'stream.
cacheObject. If type is 'cacheObject, then a reference to a frame, else NIL.
inputStream. If type is 'stream, then a reference to an input stream, else NIL.
mimeType. The MIME type of the data. This is provided for the case where the content is cacheObject, since there's no way to tell the MIME type of an ordinary frame.
transReq. A transaction request frame which describes the source of the content, and may include information such as the content title.
This method is functionally equivalent to GetCachedContentByTransaction, except it takes a hashCode:
content:= TransMgr:GetCachedContentByHash(hashCode, mimeType);
This method allows you to cache content in either stream or frame format. This method returns the unique cacheID hashCode for the given transaction.
cacheID := TransMgr:CacheContentByTransaction(content, cbContext, cbMethodSym);
The parameters are described as follows:
content. A content specification frame of the same format as described in "GetCachedContentByTransaction" on page 29. If you wish to cache a raw stream, set the inputStream slot to the stream and set type to 'stream. If you wish to cache your own custom frame format, set type to 'cacheObject and cacheObject to the frame you wish to cache.
cbContext. A callback context frame.
cbMethodSym. A callback method symbol. Your callback will be called with the following frame:
Typically you will only receive an error callback if the Transaction Manager could find no way to cache the given data, or if the device storage is full.
This method is the same as CacheContent except that it accepts a cacheID hashCode directly:
TransMgr:CacheContentByHash(content, hashCode, cbContext, cbMethodSym);