All About WebLogic Passivation, Or, What Are Those BC* Files?

If you’re running Oracle Documaker Enterprise Edition and using Documaker Interactive, it’s quite possible that you have noticed a proliferation of certain files inside the root directory of your Documaker domain. Specifically the default domain, idocumaker_domain, likely has a bunch of files prefixed with "BC" followed by an alphanumeric string, and then ending with the suffix "BCD". Have you ever wondered what these files are, and why they are there?

The reason is simply stated: the Internet and it’s primary protocol, HTTP. HTTP is a stateless protocol which means that each request made from a browser to a server is independent of any previous request. In the world of business applications, sometimes multiple steps are needed to complete an operation. This means that each step in an operation needs to retain some information about what the user has done in previous steps – that is, the state of the user’s operation needs to be retained between steps. How is this accomplished with a stateless protocol like HTTP?  

Given the stateless nature of HTTP, an arbitrary request from a user cannot be distinguished from any other request from a user, and each request looks like any other request – in a sequential process, there’s no way for the server to know if this is the first or third step in a multi-step operation. Enter cookies, and not the kind you bake yourself. HTTP cookies are bits of information, specifically name/value pairs, which the server can send to a browser and the browser can store locally. Once the cookie has been created with some name/value pairs, it is given a unique identifier. From then, the browser and the server exchange the cookie with each request and response. The cookie affords a way for a server application to store user session information ("state"), since the cookie is traded back and forth with each request and response. Cookies enable applications to be stateful when communicating via a stateless protocol.

Furthermore, for Java EE-compliant application servers such as Oracle WebLogic and others, the HttpSession object allows applications to store Java objects within cookies, which facilitates the creation multi-step operations within web applications. As with most things in the programming world, this convenience does not come without some cost: HttpSession objects are held in memory of the Java EE web server, which means that should the Java EE server crash, any in-memory sessions are lost. This failure point can be mitigated by implementing multiple Java EE servers in a cluster, which allows the HttpSession object to replicated across the cluster members. This increases perceived reliability, since a user’s request can then be handled by any active cluster member. The cost, of course, being increased network traffic and some time to broadcast the changed HttpSession objects across the cluster. As user volume increases, so does the number of HttpSession objects, and as these objects change, network traffic increases. Applications can store all manner of objects within the HttpSession, and each of these consumes memory for each HttpSession and each user. This is mitigated somewhat by session invalidation, which occurs on session timeout (which is a configurable parameter with the Java EE application server) or when the user logs out — an uncertain event. Clearly the performance implications of a system weigh heavily on system design to minimize memory, network, and reliability concerns. Luckily, Oracle ADF provides the Application Module ("AM") that handles the heavy lifting for applications, and is tunable. There is a lot of detail behind the AM State Management Facility, but for our purposes we need only know that the module allows an application to store ("passivate") pending transaction state as XML data (also known as a snapshot). As you might expect, an application can also restore ("activate") pending transaction state from a previously-stored snapshot.

BUT WHAT ABOUT THESE BC*BCD files?!, you’re probably yelling right about now. Since I’ve explained some background, I can now say that these files are the the XML snapshots stored to the filesystem. But, they can also be stored to a database. As you might expect, each option (file-based or database-backed) has pros and cons. The file-based option is fine for non-production systems and is a little faster since it lacks the overhead of database interaction. You can use this option for production systems if your Java EE application server cluster utilizes a shared file system wherein each member of the application server cluster has access to the shared file system. If you choose this route for a production system, ensure that you engage appropriate subject matter experts to tune your shared file systems, as they can represent a significant bottleneck to performance if they are not tuned accordingly. In most cases for production servers, the database-back snapshot system is preferred for systems that must be highly-available and configured for failover.

The following table illustrates settings that control the passivation scheme used by Oracle WebLogic. These settings can be added to startup scripts (e.g. startWebLogic.cmd/sh and startManagedWebLogic.cmd/sh) or to the server startup parameters sheet within WebLogic console. In either case, each setting must be prefixed with -D, e.g. "-Djbo.passivationstore=file". Note that these settings apply only to the managed server running Documaker web applications (Interactive, Dashboard, and Administrator) and the SOA suite (idm_server, dmkr_server, and soa_server are the default managed server names).

Table 1. Passivation Scheme Settings

So, in conclusion, you can stop the creation of the BC*BCD files by adding the -Djbo.passivationstore=database and -Djbo.pcoll.mgr=oracle.jbo.pcoll.OraclePersistManager or -Djbo.pcoll.mgr=oracle.documaker.shared.model.DB2PersistManagerCustom settings to your WebLogic server startup scripts or Server Start tab within the WebLogic Console for managed servers hosting Documaker Web Applications. The default managed servers are idm_server, dmkr_server and soa_server although your implementation may have a different targeting. The Documaker web applications, should you need a refresher, are Interactive, Dashboard, and Administrator. Using the database-backed persistence store is desirable for clustered production environments which must be highly-available or configured for failover. You can use -Djbo.passivationstore=file for non-clustered environments, non-production environments, or clustered environments with a shared filesystem. You can also use the -Djbo.tmpdir=<?> option to specify a directory where passivation files are written in case you don’t want them in the root of the Documaker application’s domain.