~~CLOSETOC~~
<html><font color=#990000 size="+2"><b>Runtime Configuration Cache</b></font></html>

Each fabric runtime persists its data, security, application and configuration artifacts into a local configuration cache, a set of files and directories  that may be accessed via a browser, UI tools or the repository API.  Configuration cache elements are part of a federated file system whose contents are replicated across the sysplex.  When the service engine is started it locks the file system artifacts used by the configuration cache and creates a lock file to prevent the same node from being accidentally started twice.

\\ 

====Cache File System====

{{:wiki:tfcache.png?nolink |}}

The configuration file system's artifacts are managed by the fabric runtime, much like a database. A configuration file system consists of four system directories. The ''.tfcache'' directory is the main directory that holds entity repository information that contains the security database, system objects, service configuration artifacts and cache files that may be used by developers to hold their own configuration information.  Configuration artifacts are stored as objects serialized into XML object format with an extension of XDO (XML Data Objects).

The cache file system also contains a ''.dscache'' directory that holds all the data space catalogs, recovery logs, binary objects and collection content.  The cache directory also contains a separate lock file to ensure the data space cache is not accidentally opened by another application or runtime instance.  Depending on data space settings the directory may also contain a tmp directory for storing temporary files and result sets.

The ''.htcache'' directory holds Web Application information.  Nodes that host web applications use this area to keep their Web Application Archive (WAR) packages, unpacked versions of the applications and general HTML and web server logs.  This area is updated dynamically and HTTP Acceptors can be configured to automatically scan their default locations to pick up new application information or archive packages.  During debugging and design phase of composite application development this area can be populated and changed by the user directly without impact to the overall system.  Note however, that WAR files are inspected and unpacked every time an acceptor restarts and any changes to the unpacked content will be overlaid on restart.

The ''.junk'' directory holds Repository Artifacts that have been invalidated for various reasons by the Repository House Keeper Thread.  How frequently the house keeper scans the directories for changes is set in the deployment descriptor using the ''IoThreadCycle'' parameter.  The default is 1000 milliseconds.

\\ 

====Entity Repository====

The entity repository is part of the [[runtime_configuration_cache#Cache File System]].  It is the primary mechanism for persisting an engine's active configuration.  It consists of a series of directories that hold various configuration objects for artifacts, service and connections factories and contains system area that contains serialized system configuration objects.  It is not recommended that users edit artifacts by hand, but rather use the SLANG language environment or the API.

It is possible to add configuration artifacts to the repository in several ways.  When using an API or language environment, artifacts such as Service Configuration Object, Event Prototype or Connection Factory will be written directly to the repository and locked as part of the operation.  Alternatively, users may copy such artifacts to the repository manually.  Once copied to the repository a house keeper process will identify the new file and attempt to verify and load it into memory.

Certain repository artifacts such as semantic types, event prototypes and clustered entities (if supported) will be replicated across the sysplex when repository coherence is enabled.  This ensures critical configuration information is shared with all application fabric members.  Note that security information, global variables and other internal configuration data are always replicated as part of the application fabric’s Federated Architecture.

The repository also allows users to maintain their own configuration artifacts of arbitrary type in the repository.  Such artifacts may be configured to expire.  When artifacts expire they are removed from the cache and raise and event advising that a repository state change has occurred.  The runtime allows developers to subscribe to repository state change events.

Objects may also be persisted into the repository much in the same way as Java JNDI services allow developers to persist objects.  The objects can be organized into contexts which are expressed as directories for storage purposes.  Objects are bound to names within a specific context.  Within a given context duplicate names are not allowed.  The entity repository provides a complete API for working with objects, organizing them into contexts and searching the repository by object type and name.

For additional information on working with the API see com.streamscape.repository.RepositoryContext in the platform’s Java Documentation.  

<WRAP round tip>
When the engine shuts down it performs automatic cleanup up the Application Dataspace store, releases all locks on the repository files and updates the document expiration cache.  Finally it removes temporary worker files in the dataspace persistence cache (''.dscache'') directory and performs general stability verification of the repository persistence cache (''.tfcache'') in order to bring the persistence mechanisms into a stable state.  

During the shutdown operation an engine may create temporary files with extensions ''.new'', ''.old'' and ''.rcv'' in the cache areas.  Such files should not be touched or deleted by the user.  At the time of next start-up such files are used to perform recovery and reconciliation, especially in cases where the runtime environment has shut down unexpectedly in the middle of a disk write operation.
</WRAP>

\\ 

====Data Space Storage====

The ''.dscache'' directory contains files that hold Application Data Space™ information.  Depending on the type of memory model and data collections defined, this directory may hold any combination of the following files:

^ File Name ^ Description ^
| dtspace.dat.XXX.v | Version files of data elements used during shutdown and restart.  |
| dtspace.log	    | Transaction log that contain a complete data store structure initialization log. |
| dtspace.log.idx   | Transaction log index that assists in log processing.  Recreated automatically if deleted.|
| dtspace.err       | Recovery Log errors that are extracted as transactions during recovery. |
| dtspace.dat 	    | Binary data that is held in long term (PERSISTENT) data collections. |
| dtspace.rcv       | Recovery log along with session level information that works with the log. |
| dtspace.rcv.idx   | Recovery log index that assists with recovery processing.  Recreated automatically if deleted.|
| dtspace.lob 	    | Binary objects stored as indexed Large Objects (LOBS). |

These files are used to hold schema definitions, transaction logs, data and binary objects.  If a File Space is defined that contains Directory or File Table collections, those files may also become part of the data space storage system, however they will not be located or moved into  the dataspace cache area.

The ''.dscache'' directory may also contain a tmp sub-directory used for holding transient data such as query result overflow and temporary files created during data materialization or similar data store operations.  For ''LOGGED'' and ''PERSISTENT'' collections as well as File Tables data content may grow very quickly.  As such the size of the cache should be monitored, similar to the way conventional databases are managed.
Due to the transient nature of service engine data and replication capabilities of the data space it is possible to place cache data on a RAM drive or CacheFS system, thereby providing a very fast persistence mechanism at the cost of reducing reliability.

\\

====Web Server Storage====

A runtime’s Web HTTP Acceptor functions like an independent localized Web Server.  Multiple acceptors may be defined within the same service engine, allowing the engine to potentially act as a DMZ node by assigning different levels of security and authentication to specific acceptors.  Alternatively acceptors may bind to different network interface cards and function as bridges

{{:wiki:htcache.png?nolink |}} \\ 

The ''.htcache'' directory holds information for all HTTP Acceptors.  Each acceptor instance will have its own sub-directory.  The web server cache area may be partitioned for usage thru the use of Realms, defined in the acceptor’s configuration.

This area also contains the error log and acceptor-specific traces written by the Web Server.  Acceptor traces are independent of the application fabric TRACE facility and are provided specifically for monitoring HTTP traffic and debugging purposes.  It is recommended that the traces and error log are turned off during normal node operations.  Web traffic and Security Advisories are handled independently by the service engine and may provide usage information without writing to acceptor trace files, which may grow very quickly if HTTP content tracing is enabled.

\\ 

====Web Access to Configuration Cache====

The configuration cache may be accessed thru a standard web browser interface. All major browsers are supported and allow users to work with service configuration artifacts and view configuration elements as XML documents.

{{ :wiki:sor.png?nolink|}}

Access is only available to users with administrative rights or Groups with administrative privileges. The browser based interface provides facilities for uploading configuration files, ability to browse on-line documentation for Functions, Triggers, Event Handlers and Data Objects that is added by the user, as well as auto-generated documentation for REST by user.   New artifacts are validated and processed by the house keeper thread.  Service interfaces may also be inspected using the browser, allowing users to query and download service interface artifacts. See the platform’s Java Documentation for examples.
