Stashers provide a way for the NetHopper Cache Manager to automatically access content data which is stored in a compressed format. This allows various Stashers to be plugged into NetHopper to provide the end user with compressed documents.
When the Cache Manager is looking for some content it will query installed Stashers to find out whether any Stasher contains the content requested.
After a Stasher registers, it will be queried every time NetHopper needs some content which might be cached. Because of this, Stashers should be have the ability to quickly determine whether they can provide a given piece of content based on URL.
So a typical interaction with a Stasher is as follows:
Your Stasher needs to register with the NetHopper Registration Manager upon installation. Use the following method:
RegistrationManager:RegStasher(StasherSym, infoFrame);
In this case, infoFrame contains the following slots:
codeFrame This is a reference to a frame that implements all of the required Stasher methods. (It doesn't matter to NetHopper whether this frame is read-only.)
name This is a user-viewable string that might be used to help the user pick an appropriate Stasher.
preferencesForm This slot should contain a reference to any preferences view template you might have for configuring your Stasher. This view might contain things like "resolution" or "bit-depth" preferences in the case of a graphics Stasher. The default value is NIL, no preference view. If this slot exists and is non-NIL, this view will be displayed when the user picks "(name) Prefs" in the NetHopper preferences view. Note that you'll typically use system methods such as GetUserConfig(?) and SetUserConfig(?) to persistently store and retrieve these preferences. Note that this view template must use protoPrefsRollItem as its template and must have its overview slot set to the name of this prefs view as it should appear in the NetHopper prefs.
mimeTypes. This is any array of MIME type frames which indicate the kinds of data your Stasher can store. Typically you'd only register one data type, but your Stasher might be able to store multiple types.
To unregister your Stasher, call the following Registration Manager unit method:
RegistrationManager:UnRegStasher(StasherSym);
You need to make certain that StasherSym is the same for Reg and UnReg.
Your Stasher needs to provide a few interface methods: these are described in the sections that follow.
NetHopper uses this method to determine whether your Stasher can provide the content given by the hashCode in question.
contentTypeAvailable := Stasher:HaveContent(hashCode);
If you return any value but NIL, it is likely that NetHopper will subsequently call your GetContent method with this same hashCode. Therefore, if your Stasher has some way of caching a reference to the given content without adding too much overhead, you might consider adding that capability to this method, if that would save a significant amount of time on the subsequent GetContent call.
This method should return one of three values: 'cacheObject to indicate that your Stasher has stored this content in frame format, 'stream to indicate that this content has been cached in stream format, or NIL to indicate that your Stasher does not have the given content.
This method takes a content object and stashes it.
Stasher:StashContent(content, hashCode, transReqFrame);
Where content has the following format:
type. This slot should contain a symbol: 'cacheObject or 'stream, or 'rawBlock.
inputStream. If type is 'stream then this slot should contain a reference to a data input stream.
inputBlock. If type is 'rawBlock then this slot contains a single binary object which contains all of the content data. Note that you can only stash an inputBlock-- you must always return either a stream or a cacheObject in GetContent.
cacheObject. If type is 'cacheObject then this slot should contain a reference to a frame object to be stashed.
mimeType. This indicates the MIME type of the content data. You should store this information along with the other content data so that you can return the type when this item is requested from your stash.
transReq. This contains the original transaction request frame which yielded the given content data. You MUST store this frame along with the content data and be prepared to modify and return it later (at GetContent time).
NetHopper uses GetContent to obtain data from your stash.
content = Stasher:GetContent(hashCode);
NetHopper provides this method with an integer hashCode as the key.
You simply return a content frame containing type, inputStream (if any), cacheObject (if any), mimeType, and transReq.
Sometimes the Cache Manager needs to obtain a list of items stored in your Stasher.
itemsList := Stasher:GetStashedItemsList(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. If this slot is NIL, you should return a list of all items.
The sortOn slot contains a symbol which indicates the sort order of the returned array. Currently there is only one defined symbol: 'viewDate. This value indicates that you should return your resorts sorted by access-date:
This method is called to delete an item from your stash. This method is passed a single parameter: the hashCode of the item to be deleted.
Stasher:DeleteStashedItem(hashCode);
If your Stasher does not have this item stashed, simply do nothing.
This method returns an integer value indicating the number of bytes of persistent storage space used by the Stasher. For instance, if you store data in a soup and the soup is 40,000 bytes in size, return 40000.
The NetHopper Core calls this method to find out how much space your Stasher is using.
The NetHopper Core calls this method to tell your Stasher to reduce its storage consumption to the size in bytes indicated.
Stasher:CompactStash(sizeGoal);
When your Stasher receives this call, it should start eliminating items from its cache (probably according to user preferences) until it meets the sizeGoal given.
This method sets the attributes of the transaction request stored along with the cache item.
Stasher:SetStashedItemAttributes(hashCode, changedTransReqAttributes);
Where
hashCode is the cacheID of the cache item to be modified.
changedTransReqAttributes is a frame containing one or more slots to be changed in the transaction request frame stored along with the cached item. You can use code similar to the following to make the change:
foreach slot, value in changedTransReqAttributes do curTransReq.(slot) := value;
Note that you may need to flush the change to your store by using something like EntryChangeXmit.