24.3 System Configuration

Description
Parameters
Modules
Instance Types
Module Nodes
Module Menu Subtree Extraction
Default Query Hints
Hide Entity Types

System configuration defines the modules to load and configures the InstanceTypes that are composed of modules. Exactly one system InstanceType is required, and zero or many regular(subsystem) InstanceTypes can be configured.

The conf/system-config.xml is packaged inside war:

	WEB-INF/classes/conf/system-config.xml

It can be overridden by creating conf/system-config.xml under installation directory.

	<cmobilecom.home>/conf/system-config.xml

For example, conf/system-config.xml


<system-config xmlns="http://xmlns.cmobilecom.com/xml/ns/af/system-config"
			   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
			   xsi:schemaLocation="http://xmlns.cmobilecom.com/xml/ns/af/system-config system-config_1_0.xsd"
			   version="1.0">

	<description>
	<![CDATA[
	#{bundle.About_CmobilecomAF_Examples}
	<p>
	<a href="http://Cmobilecom-AF-Examples.com" target="_blank">http://Cmobilecom-AF-Examples.com</a>
 	]]>
	</description>

	<param name="supported.locales" value="en-US,en,zh-Hans-*,zh-Hans,zh-Hant-*,zh-Hant,zh-*,zh" />

	<param name="resource.bundle.locales" value="zh,zh-Hant" />

	<param name="password.policy" value="8,ULNS"/>

	<module name="System">
		<class>com.cmobilecom.af.module.system.SystemModule</class>
	</module>

	<module name="HR">
		<class>com.cmobilecom.af.example.hr.HrModule</class>
	</module>

	<instance-type id="system" name="System">
		<version>5.19</version>
		<icon>/images/icon.png</icon>
		<logo>/images/logo.png</logo>

		<domain>system.Cmobilecom-AF-Examples.com</domain>

		<module-node module="System" />

		<!-- mapped to a persistence unit defined in META-INF/persistence.xml -->
		<persistence-unit>system</persistence-unit>
	</instance-type>

	<instance-type id="hr" name="HR">
		<version>5.19</version>
		<icon>/images/icon.png</icon>
		<logo>/images/logo.png</logo>

		<domain>hr.Cmobilecom-AF-Examples.com</domain>
		<domain>localhost</domain>

		<!-- containers: default is manageCntrBean -->
		<module-node module="HR" />

		<module-node module="System" />

		<!-- file size limit -->
		<param name="upload.max.file.size" value="5M" />
	</instance-type>

</system-config>

See System Config XML Schema for detail.

Description

The description is HTML code that will be shown under the About/Application in the Help menu. It can contain bundle expressions such as #{bundle.Key} that will be resolved by application resource bundles (<appRootDir>/resources/bundle/messages*.properties).

Parameters

A parameter defines a name/value pair. A parameter in an InstanceType will override its corresponding global parameter with the same name. Supported Parameters:

secure.redirect: defines whether to redirect to secure HTTPS from HTTP. default is false.
secure.redirect.port: defines the secure port number to redirect if secure redirect is enabled. default is 443.
supported.locales: defines a list of language ranges as supported locales. (see Locale.filter(LanguageRanges) javadoc)
resource.bundle.locales: specifies the list of language tags for which resource bundles are created. English is the ROOT and do not need to be included.
password policy: password minimum length followed by the character types that a password must contain. uppercase(U) letter, lowercase(L) letter, letter(l), number(N), special character(S).
show.entity.version: (boolean)whether to show entity version to help debug with optimistic locking.
upload.max.file.size: file size limit(in G/M/K) for upload.
email.domain: for resolving expression #{email.domain} in MailTemplates.

Modules

Specify the modules to load before adding them to configured instance types. To load a module, specify module name and its Module implementation class.


	<module name="System">
		<class>com.cmobilecom.af.module.system.SystemModule</class>
		<param name="help.enabled" value="false" />
	</module>

If the module has implementation for web, the class name will be replaced at loading time. For example,

	com.cmobilecom.af.module.system.SystemModule

will be replaced by:

	com.cmobilecom.af.module.system.web.WebSystemModule

The order of loading modules is important if there is any dependencies between modules. If Module B has dependencies on Module A, load Module A before Module B.

The module parameter "help.enabled" indicates whether help is enabled for the module. default is true. If disabled, the Help menu nodes for entities of the module will not be shown.

Instance Types

The system InstanceType (id is "system") is required, and one or more subsystem InstanceType(s) can be configured. Each InstanceType defines id, name, version, logo, icon, bound domains, module nodes, and persistence unit name.

Id: instance type id. Alphanumeric, no space or special characters, max length is 10.
Name: instance type name. Application resource bundles will be used for display name.
Version: instance type can have a version. variable 5.19 will be replaced by root project version.
Logo/Icon: image file path (starting with /) under site or inside war.
Domain: an instance type can be bound to one or more domains.
Module node: a module node refers to a Module and can have child module nodes.
Parameter: an instance type inherits global parameters and can override them.

Module Nodes

A module node can have child module nodes. For example,


	<module-node module="Website">
		<module-node module="FTP" visible-name="Websites">
			<param name="docBase" value="#{dataAccessUnit.home}/www" />
		</module-node>

		<containers>
			<indexCntrBean/>
			<manageCntrBean/>
		</containers>
	</module-node>

FTP module is embedded into Website module for file transfer. The param "docBase" of the FTP module is set to the parent directory of the sites of the DataAccessUnit so that the FTP module can transfer files for all sites.
containers: a list of containerBeans where the module node is visible. default is manageCntrBean. If a module node is not visible for a ContainerBean, its child module nodes will not be visible for the ContainerBean.
module: module name that refers to a loaded module.
visible-name: module visible name. If not specified, use module default visible name.
param: a module node can define parameters that will be used by its module.

Module Menu Subtree Extraction

A subtree of child module menu can be extracted and added to its parent module. For example,


	<module-node module="Sales">
		<module-node module="Pay">
			<menu-node-factory name="default" data-access-unit-type="instance">
				<extract-menu-node path="Settings/PaymentMethods" parent-menu-node="Settings"
								   before-menu-node="CustomerGroups"/>
				<extract-menu-node path="Payments" before-menu-node="Shipments"/>
			</menu-node-factory>
		</module-node>
	</module-node>

Suppose the Sales module has the following menu:

	Sales
		Settings
			Initialize
			Products
			PriceList
			CustomerGroups
		Orders
		Invoices
		Shipments

And the Pay module has the following menu:

	Pay
		Settings
			Initialize
			PaymentMethods
		Payments

Pay module is added as a child module of Sales module. The Pay module configures a menu-node-factory that is enabled for instances only. "Settings/PaymentMethods" of Pay module is extracted and added under the "Settings" (before "CustomerGroups") of parent Sales module. "Payments" of the Pay module is extracted and added under the root (before "Shipments") of parent Sales module.

For instance DataAccessUnit(s), the resulting Sales module menu with embedded Pay module:

	Sales
		Settings
			Initialize
			Products
			PriceList
			PaymentMethods
			CustomerGroups
		Orders
		Invoices
		Payments
		Shipments

For instanceType DataAccessUnit, menu-node-factory configuration will not be applicable, and so the whole menu of the Pay module will be appended to its parent menu. The resulting Sales module menu with embedded Pay module:

	Sales
		Settings
			Initialize
			Products
			PriceList
			CustomerGroups
		Orders
		Invoices
		Shipments
		
		Pay
			Settings
				Initialize
				PaymentMethods
			Payments

menu-node-factory: specifies the MenuNodeFactory that will create the module menu. If the name is not specified, the "default" MenuNodeFactory of the module will be used. The data-access-unit-type attribute specifies the type of DataAccessUnit(s) to which the menu-node-factory element will apply. If not specified, it will apply to both instance and instance type DataAccessUnit(s).
extract-menu-node: extract a subtree of the module menu to add. If not specified, default to the whole menu.
parent-menu-node: the menu node path under parent module root node, under which to add the extracted subtree.
before-menu-node: specifies where to insert the extracted subtree under the parent-menu-node. default: append to the end.

Default Query Hints

By default, the query scope for an InstanceType DataAccessUnit includes all its instances. To exclude instances from the query scope, pass a QueryHints(instance=null) object to PersistenceEntityManager at runtime, or add the following default query-hints:

	<instance-type id="hr" name="HR">
		<query-hints data-access-unit-type="instanceType">
			<hint name="instance" value="NULL"/>
		</query-hints>	
	</instance-type>

Hide Entity Types

Entity types can be hidden for DataAccessUnit(s), which will be invisible from user's view. For example, Hide "Security Settings" for instance DataAccessUnit(s).

	<instance-type id="hr" name="HR">
		<entity-type-invisible name="com.cmobilecom.af.entity.system.SecuritySettings"
						   data-access-unit-type="instance"/>
	</instance-type>

← Database Descriptor→ MultitenantFrames / No Frames