About the Oracle BI Presentation Catalog
The Oracle BI Presentation Catalog stores the content that users create in a directory structure of individual files.
This content includes folders, shortcuts, Oracle BI EE objects (such as analyses, filters, prompts, and dashboards), and Oracle BI Publisher objects (such as reports and templates).
This section contains the following topics:
Objects in the Catalog
The figure below shows sample objects in the catalog, as seen in Presentation Services.
Guidelines for Object Names
Each object in the catalog is stored in its own file. For example, an analysis called Analysis 1 is stored in a file named Analysis1. The object name that is visible to users, such as Analysis 1, is referred to as the logical object name.
The following list provides guidelines for object names:
-
No restrictions exist on which characters are allowed in the logical name of an object in the catalog, provided that the characters are valid Unicode characters. The following are valid logical names:
Hello World Profit / Loss % Sales * $ Cost ~~ $ "Expense"?
-
The length of the logical object name must not exceed 256 Unicode characters.
-
The length of the logical path name for an object must not exceed 16000 Unicode characters.
-
The number of directory segments in a logical path name for an object must be not exceed 255 segments.
For example, a directory with a name such as /n1/n2/n3/n4/…./n253/n254/n255 is acceptable, while a name such as /n1/n2/n3/n4/…./n254/n255/n256 is unacceptable.
-
When you pass the path name of an object using SOAP, you must escape the following characters:
Forward slash (/) Backward slash (\) Tilde (~) Asterisk (*) Question mark (?)
The following logical path names are all valid:
/shared/test/Hello World /shared/test/Profit \/ Loss /shared/test/% Sales \* $ Cost \~\~ $ "Expense"\?
Use care when building a catalog path. It is very common to see code that assumes the forward slash (/) is always a path separator. Always verify your path code with an object name such as "Profit / Loss".
-
When you pass a catalog search filter using SOAP, you must escape the following characters:
Forward slash (/) Backward slash (\) Tilde (~) Asterisk (*) Question mark (?) Caret (^) Dollar sign (?)
The following search filters are all valid:
Hello World Profit \/ Loss % Sales \* \$ Cost \~\~ \$ "Expense"\?
Attribute Files for Objects
Each object has a corresponding attribute file. For example, the analysis called Analysis1 would have a corresponding attribute file named Analysis1.atr. The attribute file contains the object's full name, access control list (ACL), description, and so on. To access an object in the catalog, users must have appropriate ACL entries for that object. All objects in the catalog use ACL entries.
Lock Files for Objects
To guarantee that only one user can write to a file at one time, a lock file is created when an object is being written to. On rare occasions (for example, after a power outage), temporary lock files in the catalog might not be removed completely. If Presentation Services reports of such a lock file, then you must delete it manually.
File System Guidelines for Catalogs
This section describes the guidelines for working with objects in catalogs in file systems.
Handling Users of the Catalog
The catalog is designed to scale to thousands of concurrent users. To achieve this scaling, the catalog adheres to the following guidelines:
-
The average user typically only reads from the catalog and rarely, if ever, writes to it. Each user is constantly and automatically updating his or her Most Recently Used file, but each user's "read" operations still far outweigh the user's "writes" operations. Therefore, the read-to-write ratio is typically at least 100 to 1.
-
While a locking mechanism guarantees that only one user can write to an object at a time, it is rare for multiple users to attempt to write simultaneously to the same object. A feature called "lazy locking" enables users to continue reading an object even when another user is updating that object.
-
Modern file systems cache "small" files directly inside the directory record, such that reading any information on a directory simultaneously loads all small files directly into the operating system's memory cache. Therefore, it is good practice to keep files in the catalog "small," especially the frequently "read" .atr metadata files. When these metadata files remain small, then all the .atr files in a directory are loaded into memory with one physical hard disk read. Every file that exceeds the "small" threshold adds another physical hard disk read, which can cause a 100% degradation for each large file. In other words, use care when considering storing arbitrary "Properties" in .atr files.
-
Reading an object's .atr metadata file using NFS is far slower than reading it directly from a local disk. For this reason, Presentation Services additionally caches all .atr files internally. This cache can become briefly "stale" when another node in the cluster writes data to the file that is newer than the data that is cached by the current node. Therefore, all nodes are refreshed according to the MaxAgeMinutes element in the instanceconfig.xml, whose default for a cluster is 5 minutes. This default setting commonly achieves the best trade-off between the possibility of stale data and the known performance impact. (The default for an environment without clusters is 60 minutes.)
You can modify the MaxAgeMinutes element for your system. Its parent elements are Cache and CatalogAttributes.
Handling Heterogeneous Nodes
To allow heterogeneous nodes in a cluster, the catalog adheres to the following guidelines:
-
The maximum length for the name of an object on disk is 256 bytes, which is 64 Unicode characters. The logical name is restricted to 256 Unicode characters. To adhere to this restriction, logical names greater than 32 characters are hashed.
-
The maximum length for the name of a path on disk is 32KB, which is 8000 Unicode characters. The logical path is restricted to 16000 Unicode characters.
-
All path names on disk are all lowercase. The logical path name allows mixed case, but is still case-insensitive.
-
Certain characters are not allowed for path names on disk, while the logical path name allows all characters. For example, Windows systems disallow certain characters such as the colon (:), so those characters are mapped using standard HTML escape sequences. For example, the period character (.) becomes "%2e".
-
Certain file names are not allowed on disk, while the logical object name has no restrictions. For example, Windows systems disallow certain file names such as COM, so those names are mapped using standard HTML escape sequences. For example, "com" becomes "co%6d".
Handling Catalog Files on Various Platforms
Keep the following points in mind when handling catalog files on various platforms:
-
For UNIX Platforms: UNIX kernels must commonly be configured to allow more than 4000 subdirectories per directory. See Manually Changing Configuration Settings for the Catalog for information on the HashUserHomeDirectories element.
-
For Windows Platforms:
When users want to navigate catalog files using a tool such as Microsoft Windows Explorer, then they want the catalog structure based on a short path name such as c:/obi/demo, rather than the long default path name. Note that such navigation is not recommended.
-
FAT is not supported, and NTFS is required.
-
Performance on Windows platforms degrades noticeably when more than 8000 files exist in a single directory. Because each catalog object has two files (the data file and the .atr metadata file), it is strongly recommended that you not store more than 4000 catalog objects in a single directory.
-
Windows Explorer does not handle long path names properly, and it is recommended to not use Windows Explorer to navigate the internal structure of the catalog. While the file system can handle path names as large as 32KB and Presentation Services is not negatively affected, you cannot use Windows Explorer with any path name that is longer than approximately 2KB.
Because a single Unicode character can require as many as 4 bytes, you might be unable to use Windows Explorer with path names of only 500 Unicode characters. This limitation does not affect Presentation Services. Because of this limitation, place the catalog in a top-level directory, such as c:\mycatalog\sales.
-
Known Issues with Catalog Files
The following issues are known when working with catalog files:
-
Locking across NFS systems is difficult, but Presentation Services provides an effective locking mechanism in recent versions. Obtain key patches to update older versions of Oracle BI EE as necessary.
-
Various third-party FTP programs have issues handling '%' escape sequences, which often results in a renamed file that is doubly escaped. For example, a file that is named sa%2epaint (whose logical name is SA.Paint) is incorrectly renamed to sa%252epaint (whose logical name is SA%2ePaint).
Avoid using an FTP program directly against a catalog. Instead, download and use the 7-Zip utility to compress the catalog files, then use an FTP program to transfer the resulting compressed file.