Oracle® Fusion Middleware Developer's Guide for Oracle Universal Content Management 11g Release 1 (11.1.1) Part Number E10807-02 |
|
|
View PDF |
This chapter describes the architecture of Oracle Universal Content Management (Oracle UCM) in the context of what you need to know before beginning a customization project. To create a customization efficiently and effectively, you should have an understanding of how Oracle UCM works.
This chapter includes the following sections:
When you create custom components or dynamic server pages, you work primarily with files in the bin, config, components, resources, and weblayout directories. The following sections describe these directories:
Section 2.1.6, "The weblayout Directory"
Caution:
Modifying the default variables in these files can cause Oracle UCM to malfunction. For more information about configuration variables, see the Oracle Fusion Middleware Idoc Script Reference Guide.Oracle UCM documentation uses the following terms when referring to variables in the directories associated with the Oracle UCM installation, configuration, and deployment:
IdcHomeDir: This variable refers to the ucm/idc directory in the ECM Oracle home where the Oracle UCM server media is located. The server media can run Oracle Content Server, Oracle Inbound Refinery, or Oracle Universal Records Management. This is essentially a read-only directory. The default location is ECM_ORACLE_HOME/ucm/idc. The variable portion of the default location can be changed, but the path cannot be changed at ucm/idc.
DomainHome: The user-specified directory where an Oracle UCM server is deployed to run on an Oracle WebLogic Server application server. The DomainHome/ucm/short-product-id/bin directory contains the intradoc.cfg file and executables. The default location for DomainHome is MW_HOME/user_projects/domains/base_domain/, but you can change the path and domain name (base_domain) during the deployment of Oracle UCM to Oracle WebLogic Server.
short-product-id: An abbreviated name for the type of Oracle UCM server deployed to an Oracle WebLogic Server domain, and it is used as the context root (default HttpRelativeWebRoot
configuration value). Possible values follow:
cs
(Oracle Content Server)
ibr
(Oracle Inbound Refinery)
urm
(Oracle Universal Records Management)
IntradocDir: The root directory for configuration and data files specific to an Oracle Content Server instance that is part of an Oracle UCM application deployed to an Oracle WebLogic Server domain. This Idoc Script variable is configured for one type of Oracle Content Server instance: Oracle Content Server (cs
), Oracle Inbound Refinery (ibr
), or Oracle Universal Records Management (urm
). This directory can be located elsewhere, but the default location is DomainHome/ucm/short-product-id/. The specified directory must be an absolute path to the instance directory, and it must be unique to a particular server or node. The directory files include startup files (intradoc.cfg and executables).
The bin directory is the root directory for Oracle Content Server startup files. It contains the intradoc.cfg file and the executable files that run Oracle Content Server services, applets, and utilities. It is located at DomainHome/ucm/short-product-id/bin, in which short-product-id specifies whether it is for Oracle Content Server, Oracle Inbound Refinery, or Oracle Universal Records Management.
Element | Description |
---|---|
Executables | Services |
intradoc.cfg file | Configuration file that contains the settings for Oracle Content Server services, applets, and utilities. |
Note:
If Oracle Content Server is set up as an automatic service and you attempt to start an Oracle Content Server service (IdcServer or IdcServerNT) from the command line, you will receive an error message:The port could not be listened to and is already is use.
The intradoc.cfg file is used to define system variables for Oracle Content Server, including directory, Internet, and refinery settings. Several of these variables can be set using the Oracle Content Server System Properties utility.
A typical intradoc.cfg file follows:
<?cfg jcharset="Cp1252"?> #Oracle Content Server Directory Variables IntradocDir=C:/oracle/idcm1/ WebBrowserPath=C:/Program Files/Internet Explorer/iexplore.exe CLASSPATH=$COMPUTEDCLASSPATH;$SHAREDDIR/classes/jtds.jar #Additional Variables HTMLEditorPath=C:/Program Files/Windows XP/Accessories/wordpad.exe JAVA_SERVICE_EXTRA_OPTIONS=-Xrs
The config directory stores global configuration information for Oracle Content Server. This directory can be located elsewhere, but the default location is DomainHome/ucm/short-product-id/config.
Element | Description |
---|---|
config.cfg file | Defines system configuration variables. |
The config.cfg file is used to define global variables for the Oracle Content Server system. Several of these variables can be set using the Oracle Content Server System Properties utility or by modifying the variables on the Admin Server General Configuration page.
A typical config.cfg file follows:
<?cfg jcharset="Cp1252"?> #Oracle Content Server System Properties IDC_Name=idcm1 SystemLocale=English-US InstanceMenuLabel=JeanWTestSystem InstanceDescription=idcm1 SocketHostAddressSecurityFilter=127.0.0.1|10.10.1.14 #Database Variables IsJdbc=true JdbcDriver=com.internetcds.jdbc.tds.Driver JdbcConnectionString=jdbc:freetds:sqlserver://jwilsonnote:1433/oracle1;charset=UTF8;TDS=7.0 JdbcUser=sa JdbcPassword=UADle/+jRz7Fi8D/VzTDaGUCwUaQgQjKOQQEtI0PAqA= JdbcPasswordEncoding=Intradoc DatabasePreserveCase=0 #Internet Variables HttpServerAddress=jwilsonnote MailServer=mail.example.com SysAdminAddress=sysadmin@example.com SmtpPort=25 HttpRelativeWebRoot=/oracle/ CgiFileName=idcplg UseSSL=No WebProxyAdminServer=true NtlmSecurityEnabled=No UseNtlm=Yes #General Option Variables EnableDocumentHighlight=true EnterpriseSearchAsDefault=0 IsDynamicConverterEnabled=0 IsJspServerEnabled=0 JspEnabledGroups= #IdcRefinery Variables #Additional Variables WebServer=iis UseAccounts=true IdcAdminServerPort=4440 SearchIndexerEngineName=DATABASE VIPApproval:isRepromptLogin=true Vdk4AppSignature=SF37-432B-222T-EE65-DKST Vdk4AppName=INTRANET INTEGRATION GROUP IntradocServerPort=4444
The IntradocDir/data/components directory contains the files that Oracle Content Server uses to configure system components.
The following example file is a component.hda file that defines the configuration status for a component called help.
<?hda version="11.1.1.2.0-dev idcprod1 (091209T125156)" jcharset=UTF8 encoding=utf-8?> @Properties LocalData blDateFormat=M/d{/yy} {h:mm[:ss] {aa}[zzz]}!tAmerica/Chicago!mAM,PM @end @ResultSet Components 2 name location help components/help/help.hda @end
The IdcHomeDir/resources directory contains two directories: admin and core.
The resources/core directory contains files that Oracle Content Server uses to assemble web pages.
The resources/admin directory contains the following resource types.
Resources are files that define and implement the actual customization you make to Oracle Content Server. They can be pieces of HTML code, dynamic page elements, queries that gather data from the database, services that perform Oracle Content Server actions, or special code to conditionally format information.
Resources are a critical part of the Oracle Content Server software, so you must be familiar with them before you attempt to create a custom component or dynamic server page. You can create, edit, or remove a resource file by using the Component Wizard. You also can use the Component Wizard as a starting point for creating custom resources.
Resources fall into distinct categories, although the first five types listed in the following table are also called Resource-type resources.
The following sections describe how Oracle Content Server behaves in different situations:
The following steps occur during Oracle Content Server startup:
Internal initialization occurs.
Configuration variables load.
Standard templates, resources, and reports load.
Custom components load (templates, resources, configuration variables, and reports).
Figure 2-1 illustrates these steps in a flowchart. Section 2.3.1.1, "Startup Steps," describes each step in more detail.
Figure 2-1 Oracle Content Server Startup Behavior
Here are descriptions of the steps that an Oracle Content Server instance goes through during startup:
Internal Initialization Occurs: When Oracle Content Server initializes internally, the Java class files from Oracle Content Server are read and the Java Virtual Machine (JVM) is invoked. Any variables in the DomainHome/ucm/short-product-id/intradoc.cfg file initialize as well.
Configuration Variables Load: After initializing, Oracle Content Server loads the config.cfg file from the IntradocDir/config directory. This file stores the system properties and configuration variables, which are defined by name/value pairs (such as SystemLocale=English-US).
The default information contained within the configuration file was supplied during the Oracle Content Server installation process, but you can modify this file in several ways:
By using the Admin Server General Configuration page, accessible from the Administration menu.
By using the System Properties option, which is available from the Start menu (in Windows) or by running the SystemProperties script, located in the bin directory of your installation (on a UNIX operating system).
By editing the configuration files directly.
By using a custom component.
Any time changes are made to the config.cfg file, you must restart Oracle Content Server for the changes to take effect.
Standard Resources, Templates, and Reports Load: For Oracle Content Server to function properly, many standard resources, templates, and reports must be loaded. After the configuration settings have been loaded, Oracle Content Server reads the entries in the IdcHomeDir/resources/core/templates/templates.hda file and the IdcHomeDir/resources/core/reports/reports.hda file. These files tell Oracle Content Server which templates to load, which in turn loads any standard resources referenced in the template and report pages.
Custom Components Load: Oracle Content Server loads resources in the order specified in the IntradocDir/custom/components.hda file.
It is important to understand the effect of the load order of the different configuration files because if a variable is set in more than file, the last variable loaded takes precedence. For example, the IntradocDir/config/config.cfg file is loaded first, and the IntradocDir/data/components/component_name/config.cfg file is loaded last, so the component_name/config.cfg can change the value of a variable that was set by the config/config.cfg file.
Files are loaded in this order (not all files exist for each component):
IntradocDir/config/config.cfg.
DomainHome/ucm/short-product-id/custom/component_name/*_environment.cfg. Some components may not have this file or it may be named environment.cfg.
IntradocDir/data/components/component_name/install.cfg.
IntradocDir/data/components/component_name/config.cfg.
DomainHome/ucm/short-product-id/bin/intradoc.cfg is reread at the end of startup to allow overrides to other settings.
If, for example, a variable was set in each of the files listed previously, the variable in component_name/config.cfg takes precedence.
To view the configuration, use the GET_SYSTEM_AUDIT_INFO service to show all configuration entries and where they were set.
To change a component variable, use the Advanced Component Manager and select Update Component Configuration. This displays values in the component_name/config.cfg file that are editable. Make the desired changes, and click Update.
You can also edit the configuration file manually. If a component is not displayed in the drop-down list or if the variables displayed do not include the one to change, make the change directly in one of the configuration files.
Oracle Content Server handles caches template pages and resources as follows:
When Oracle Content Server loads template pages and resources, they are cached in memory to accelerate page presentation.
If you change a template page, report page, or HTML include resource, or you check in a revision to a dynamic server page, your changes go into effect immediately—the next request for the associated web page or refresh of the page reflects the changes and the new information is cached. This occurs because pages are assembled dynamically for each page request. You can disable this behavior to improve performance by setting the config variable DisableSharedCacheChecking.
If you change any other component files (including services, queries, environment variables, tables, components.hda file, and template.hda file), you must restart Oracle Content Server before the changes go into effect. This is because such changes could cause Oracle Content Server to malfunction if they were implemented immediately. You do not need to restart Oracle Content Server when changing strings; however, you must republish the ww_strings.js files by clicking publish dynamic files in the Weblayout Publishing area of the Admin Actions page. For more information, see Chapter 3, "Working with Standard, Server, and Custom Components."
When a web browser client sends an Oracle Content Server request to the web server, the instructions are typically communicated through URLs or form fields. The web server routes the request to Oracle Content Server, which then performs one or more of the following actions:
Retrieves pages
For more information, see Section 2.3.3.1, "Page Retrieval."
Runs an Oracle Content Server service
For more information, see Section 2.3.3.2, "Oracle Content Server Services."
Runs a search engine service
For more information, see Section 2.3.3.3, "Search Services."
Note:
Oracle Content Server uses the web server provided by Oracle WebLogic Server.When an Oracle Content Server web page is requested, all of the necessary information can be sent to Oracle Content Server through the URL. A typical Oracle Content Server URL follows, the URL for the Home page:
http://cs.example.com/instancename/idcplg?IdcService=GET_DOC_PAGE&Action=GetTemplatePage&Page=HOME_PAGE
http://cs.example.com
/instancename
is the web address of the Oracle Content Server instance.
IdcService=GET_DOC_PAGE
tells Oracle Content Server to execute the GET_DOC_PAGE service.
Action=GetTemplatePage
tells Oracle Content Server to return the results using a specified template page.
Page=HOME_PAGE
tells Oracle Content Server which template page to use.
The question mark (?) indicates the end of the web server path and the beginning of Oracle Content Server instructions.
Ampersands (&) are used as separators between Oracle Content Server instructions.
You can include some Idoc Script variables in a URL to affect page display at the time of the page request. This is useful for troubleshooting or for temporary pages. For example, the following variables can be used for customization:
&StdPageWidth=1000
&dDocAuthor:isHidden
&dDocType=HRForm
Necessary information can also be sent to Oracle Content Server through form fields on the page. A typical Oracle Content Server form follows:
<form name=SubscriptionForm action="<$HttpCgiPath$>" Method="GET""> <input type=hidden name=dID value="<$dID$>"> <input type=hidden name=dDocName value="<$dDocName$>"> <input type=hidden name=subscribeService value=SUBSCRIBE> <input type=hidden name=exitUrl value="<$HttpCgiPath$>?IdcService=DOC_INFO&dID=<$dID$>&dDocName=<$dDocName$>"> <input type=hidden name=title value="Subscriptions"> <input type=hidden name=unsubscribeService value=UNSUBSCRIBE> <$if ClientControlled$> <input type=hidden name=ClientControlled value="<$ClientControlled$>"> <$endif$> <$if DocHasSubscription$> <input type=hidden name=IdcService value="UNSUBSCRIBE_FORM"> <input type=submit value="<$lc("wwUnsubscribe")$>"> <$else$> <input type=hidden name=IdcService value="SUBSCRIBE_FORM"> <input type=submit value="<$lc("wwSubscribe")$>"> <$endif$> </form>
When a web page is requested from Oracle Content Server, the page it returns is either static dynamic:
Static page
The content of a static web page is preformatted, and does not change from one request to the next. On some Oracle Content Server web sites, the only static page is the Guest Home page (DomainHome/ucm/short-product-id/weblayout/portal.htm).
Dynamic page
A dynamic web page is assembled at the time of the web server request, using Oracle Content Server services and templates to determine the content and formatting. For example, each user's portal design page is generated using an Oracle Content Server service called GET_PORTAL_PAGE and a template called PNE_PORTAL_DESIGN_PAGE.
When a web browser requests a dynamic page from Oracle Content Server, the browser is actually placing a request for an Oracle Content Server service.
For example:
When a user clicks the Administration link in the navigation area, a request for the GET_ADMIN_PAGE service is sent to the web server.
The web server recognizes this request as an Oracle Content Server function, and sends the specific request to Oracle Content Server.
When Oracle Content Server has processed the request, it passes the result back to the web server. In the case of the Administration link, the GET_ADMIN_PAGE service:
Provides a login prompt if the user is not currently logged in.
Verifies that the user has the admin
privilege.
Assembles the Administration page, using the ADMIN_LINKS template.
Returns the assembled web page to the web server.
The web server delivers the results of the Oracle Content Server service to the originating web browser client.
A search request is a special kind of Oracle Content Server service. When Oracle Content Server receives a search request, it sends the request on to the search engine, using a search engine API. This service makes it possible to use different search engines with Oracle Content Server.
For example:
When a user clicks the Search button on the standard Search page, a request for the GET_SEARCH_RESULTS service is sent to the web server.
The web server recognizes the request as an Oracle Content Server function and sends the specific request to Oracle Content Server.
Oracle Content Server passes the request to the search engine that is configured for the Oracle Content Server instance.
The search engine returns the search results to Oracle Content Server.
Based on the user login and security permissions, Oracle Content Server assembles the search results page and returns it to the web server.
The web server delivers the results to the originating web browser client.
Oracle Content Server uses information from the files in the IdcHomeDir/resources directory to assemble dynamic web pages.
The structure and format of a web page is defined by a particular HTML template file in either the resources/admin/templates directory or the resources/core/reports directory.
The templates reference resources, which are located in .htm and .idoc files in subdirectories of the resources directory. Resources can include HTML and Idoc Script markup, localized strings, queries to gather information from the database, and special code to conditionally format the information.
As a rule, each web page includes the following resources:
Because all of the Oracle Content Server resources are cached in memory at startup, Oracle Content Server has a definition for the standard pieces that appear on the page. Oracle Content Server then combines the standard resources with the unique resources specified in the template to create the web page.
For dynamic server pages, the template page and custom resource files are checked into Oracle Content Server. When one of these pages is requested by a web browser, Oracle Content Server recognizes the file extension as a dynamic server page, which enables special processing. At that point, the page assembly process is the essentially the same as the standard process, except that the page can use both the standard resources in the resources directory and the custom resources that are checked in to Oracle Content Server.
Some databases, such as Oracle Database, return all column names in uppercase characters. Therefore, when Oracle Content Server receives query results from these databases, column names must be mapped from the uppercase characters to the values used in Oracle Content Server.
Because of this case mapping issue, custom components created for an Oracle Content Server instance using one database might not work correctly on an Oracle Content Server instance using a different database.
To map column names, the IdcHomeDir/resources/core/resources/upper_clmns_map.htm file contains a mapping table named ColumnTranslation
. Add the query values to this file when you create a component that accesses fields that are not Oracle Content Server database fields (for example, if you create a component that accesses a custom table within the Oracle Content Server database).
For information about using the upper_clmns_map.htm file, see Section 5, "Modifying System Functionality."
Localized strings are the means by which the user interface and error messages are presented in the language specified by the user's locale. Oracle Content Server loads the string resource files for a base language and also loads resource files for every supported language. Instead of presenting hard-coded text, the template pages, applets, and error messages reference string IDs in these resource files, which are then resolved using the ExecutionContext that contains the locale information for the user.