Content Management Functions

The API's content management features allow modules to perform finer-grained control over cache content than a proxy cache normally provides. These routines are appropriate for environments where the default content management behaviors of the proxy cache must be modified or augmented with information from other sources. The routines in this area fall into three broad categories: content freshness modification and eviction, content preloading, and content querying. The related functions are shown in Table 2.

Table 2: Content management functions

Naming & Identification	DR_ObjIDMake DR_ObjIDRef DR_ObjIDUnref	Modules use internal identifiers for content management functions rather than requiring full URLs in all calls. These functions are used to create/destroy the identifiers
Existence & Lifetime Handling	DR_ObjQuery DR_ObjFetch DR_ObjValidate DR_ObjExpirationSet DR_ObjDelete	For querying the existence/property of objects and loading, refreshing, and deleting them as needed
Cache Injection	DR_ObjInject DR_ObjInjectStart DR_ObjInjectBody DR_ObjInjectDone	Objects can be manually added into the proxy without having the proxy initiate a fetch from a remote server. The object can be injected all at once, or in pieces.
Data Reading	DR_ObjRead DR_ObjReadStart DR_ObjReadPart DR_ObjReadDone	Objects in the cache can be loaded into memory allocated by the module without being requested by the client. The object can be read all at once or in pieces.

Table 3: Utility functions

External Communication	DR_FDPollReadNotify DR_FDPollReadClear DR_FDPollWriteNotify DR_FDPollWriteClear DR_FDPollClose	Modules may communicate externally using sockets, even when using the callback mechanism. In this case, they use asynchronous operations and use these functions to have the main proxy notify them of events on their sockets.
Custom Logging	DR_StringFromStatus DR_StringFromLogCode DR_StringFromLogTimeout DR_StringFromLogHier	These functions provide the standard text strings used for the extended log format.
Configuration	DR_ConfigOptionFind	User modules invoke this function to extract information from the cache configuration file.

Server accelerators and surrogates in content distribution networks benefit from finer-grained control over content validation to improve response time, reduce server load, or provide improved information freshness. In particular, surrogates normally achieve the maximum benefit when the origin servers set large expiration times to reduce the frequency of revalidation. However, the proxy may not see the most recent content if the underlying content changes during this time. When an external event (such as a breaking news item) occurs that voids the expiration information, the content management routines can update the proxies by invalidating cached content and fetching the newest information. The content management routines thus allow programmed, automatic control for exceptional situations while still using the regular mechanisms of the proxy cache under normal circumstances.

The content management routines also allow programmatic and dynamic preloading of objects into the cache, in addition to the content prepositioning support that already exists in many proxy caches. Preloading modules may be coupled to information sources outside of the proxy rather than just based on timer information. For example, a service provider running a network of caches could create a custom module to inject documents into caches as their popularity increases in other parts of the network.

Finally, the content management controls can also be used to provide ``premium'' services to portions of cached content. For example, the content management controls can be used to periodically query the cache and refresh the pages of premium customers, changing their cache eviction behavior.

Even though these functions change the material stored in the cache, the API introduces no security issues because its functions are invoked directly from trusted modules running on the same machine. However, the modules themselves may need to implement a security policy, especially if they take commands from external sources. The modules may use standard library functions to provide the mechanisms for this security; the API need not provide mechanisms since none of the encryption or authentication required is specific to the proxy cache environment.