NetHopper 3.0 provides an entity called the Transaction Core, which provides services for performing web transactions, opening an NIE Internet link, queueing offline transactions, and grouping transactions.
The Transaction Core is part of the NetHopper Core package and exports a Unit interface. To access the Transaction Core, include the "NH3TransactionCore.unit" file in your project, then import the read-only Transaction Core unit reference as follows:
UnitReference( kNHTransCoreUnitSymbol,kTransCoreInterfaceSubUnitSymbol);
Note that if the NetHopper Core package isn't installed, this reference will be bogus. See the Apple documentation on Unit references for information on how to determine if a unit reference is bogus (using kMissingImportsFunc) at runtime.
Typically a Transaction Manager deals with Transaction Requests. See the URL Manipulator documentation for information on how to create a Transaction Request frame.
The Transaction Core provides access to a blank Document Container, which can then be used to perform web transactions.
This Display Manager method returns a Document Container. This Container supports the standard Container API for displaying documents.
newContainer := DiplayMgr:GetBlankContainer();
Note: A Container is just a view template with extra API, as defined in the following sections. You can instantiate a view at runtime based on the Container template. You must open the container view before calling any of the container APIs.
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.
Sometimes it's handy to be able to group several Transaction Managers together. For instance, if you're loading multiple content items for a single Web page, it might be handy to allow the user to stop all associated transactions all at once.
In NetHopper 3.0, we've introduced the concept of a Transaction Group for grouping multiple Transaction Managers together.
To create a new Transaction Group, call the Transaction Core method GetNewTransactionGroup(). To add a specific Transaction Manager to the Transaction Group, call the Transaction Group method AddTransactionMgr(transactionMgr);
The TransactionGroup StopAll method has the following behavior: All of the associated Transaction Manager's CancelTransaction methods are called in the reverse order of the way they were added to the group (last in, first cancelled).
TransactionGroup:StopAll();
The Finalize method finalizes all of the transaction managers in the transaction group.
TransactionGroup:Finalize();
You can use the Transation Core method QueueTransaction to request a delayed or deferred transaction thus:
TransactionCore:QueueTransaction(requestFrame, delay);
In this case, requestFrame is a transaction request frame, and delay is one of the following:
Note that you don't need to create your own Transaction Manager instance in order to use this method. The Transaction Core will deal with handling the transaction.
Note also that this method provides no callback mechanism. The transaction will complete or fail without calling back to your application. This is because your application might disappear before the transaction has been completed. This is similar to how your application might deal with adding entries to the outbox. Once the outbox entry has been added, your application isn't notified when the transaction has been completed.
If you want to be notified when a transaction has been completed, you should use the regular Transaction Manager interface instead.
The NetHopper Transaction Core now provides some NIE Link control methods of use to Protocols and applications.
A high-level application such as the NetHopper web browser will call these methods. The EnableLinkConnection method indicates to the Transaction Core that the application is interested in keeping the Internet Link open continuously, and not have the Internet Link be opened and closed for every single web transaction. The DisableLinkConnection method indicates to the Transaction Core that the application is no longer interested in having the Inet Link remain open. Note that neither method actually opens or closes the Internet Link-- lower-level code will take care of this when appropriate.
This method allows a Protocol or other plugin to open the Internet Link. This method simply takes a callback context and method:
transCore:GrabInetLink(cbContext, cbMethod);
Your callback will be called with the following parameters:
linkID. The NIE ID of the Link opened, or NIL.
error. An error code, if any.
This method allows a Protocol or other plugin to relinquish their interest in having the Inet Link stay open. Once all Inet Link clients have called this method and all high-level clients have called DisableInetLink, the NIE Inet Link will be closed.
This method takes no parameters and provides no callback. Once you call this method you can assume that your interest in the link has been cleared.
transCore:ReleaseInetLink();
The Transaction Core provides some basic cache methods. Additional caching methods are provided in the Transaction Manager
This method returns a list of items in the cache.
itemList := transCore:GetCachedItemsList(typesSpec);
Here, typesSpec is a frame which specifies the type of items to be listed:
The mimeTypes slot contains an array of acceptable MIME types. Specify NIL to get all MIME types.
The sortOn slot contains a symbol which indicates the sort order of the returned array. Currenty this parameter is ignored and the list is always returned in order of least-recently-viewed to most-recently-viewed order:
This method returns the cache hash code corresponding to a transaction request frame.
hashCode := TransCore:GetHashCodeForTransaction(transReqFrame);
Your application can use this result to pass to the other cache methods instead of passing a transaction request frame each time. Note that the format of the hashCode is subject to change.
This method removes the item (if any) given by the hashcode from the local cache.
cacheMgr:DeleteCacheItemByHash(hashCode);
This method's return value is currently undefined.
This method removes the item (if any) given by the transaction req. frame from the local cache. Note that this method calls DeleteCacheItemByHash implicitly, so it's a bit slower than DeleteCacheItemByHash.
cacheMgr:DeleteCacheItemByTransaction(transReqFrame);
This method's return value is currently undefined.
This method quickly determines whether the content provided by the given transaction request frame has been cached locally.
storedTypes := TransCore:IsCached_ByTransaction(transReqFrame);
If the content is not cached locally, this method returns NIL. Otherwise, it returns the Stasher which has the content cached.
This method quickly determines whether the content given by the hashCode has been cached locally.
storedTypes := TransCore:IsCached_ByHash(hashCode);
Note that this method is implicitly called by IsCached_ByTransaction (and is, therefore, faster than IsCached_ByTransaction).
This method allows you to update the attributes of the transaction request frame stored with an item in a cache. This can be useful for locking items in the cache, updating the title, etc.
newTransReqFrame := TransCore:SetCachedItemAttributes(transReqFrame, changedAttributes);
If the content is not cached locally, this method returns NIL. Otherwise, it returns the the newly modified transaction request frame as stored in the cache.
transReqFrame is the original transaction request frame for this cache item. This parameter is used to find the item in the cache.
changedAttributes is a transaction-request-like frame which contains ONLY those slots which are to be changed in the cache. For instance, to set the fLockInCache attribute to true, changedAttributes would look like:
All values in changedAttributes will be forced on the cache entry.