The Aspire Application XML file (application.xml) specifies the components (and their configurations) that together implement your application.
The system configuration file is also known as the "Component Manager" configuration file, since it is, technically, the component manager that reads the file and initializes the components.
On this page:
The configuration file can be loaded in two ways:
To load a system configuration file through the user interface, do the following:
Note: Loading a configuration file via the System Administration user interface utilizes an application servlet command. See Advanced Configuration Loading below.
You can load multiple configuration files - as many as you'd like. This is a very useful technique for organizing your application into small, easily manageable and configurable sections - one per system configuration file.
The template for the standard configuration file is as follows:
<?xml version="1.0" encoding="UTF-8"?> <application name="YOUR-APP-NAME" typeFlags="feeder,sub-jobs"> <components> ... components to create/initialize go here ... </components> </application>
Notes:
Every application contains a simple list of components. Each component can be configured with configuration XML.
Note that some components are component managers, such as the pipeline manager. These managers can have sub-components nested within them. Nested components are just like any other component and can be created and configured with XML.
The basic structure for configuring components is shown below:
<components> <component name="NAME1" subType="SUBTYPE" factoryName="FACTORY-NAME"> ... </component> <component name="NAME2" subType="SUBTYPE" factoryName="FACTORY-NAME"> ... </component> <component name="NAME3" subType="SUBTYPE" factoryName="FACTORY-NAME"> ... </component> <component name="NAME4" subType="SUBTYPE" factoryName="FACTORY-NAME"> ... </component> </components>
Notes:
Components can be disabled using @enable or @disable attributes. If both @enabled and @disabled flags are specified, the value of @enable takes precedence. Disabled components are completely removed from the system, as if they had never been written into the XML file at all.
These flags are useful for turning on or off components in response to property settings (either as an App Bundle or via property settings specified in the settings.xml file).
Example:
<!-- The next two components are declared, but never initialized. --> <component enable="false" .../> <component disable="true" .../>
If neither @enable or @disable are present, then it is assumed that the component is enabled.
If a component manager (such as a pipeline manager) is disabled, then it will not load itself, nor will it load or initialize any of its sub-components.
The following example shows a system configuration file that contains two components:
<?xml version="1.0" encoding="UTF-8"?> <application name="Example"> . . . <components> <component name="FeedOne" subType="feedOne" factoryName="aspire-tools"> . . . </component> <component name="MyProcessor" subType="default" factoryName="aspire-groovy"> . . . </component> </components> </config>
Note: The new standard is for all component names to start with an Uppercase Letter.
Technically, the above configuration will create three components:
/Example | This is the name of a component manager itself (all Aspire Applications are, in fact, component managers which contain nested components). |
/Example/FeedOne | The name of the feed one component. |
/Example/MyProcessor | The name of the job processor written in Groovy. |
Notice how the subcomponents all have the name of the component manager prefixed to them. In this way, all component names are hierarchical - like directory and file names. See Naming Components for more information.
Factory names in Aspire specify the Maven Artifact which is the JAR file that implements the required Aspire component factory. This can be specified in the Aspire System Configuration file in three different ways:
Note that the Maven packaging (i.e. "jar", "bundle" etc.) is not needed and can not be specified.
Example:
<component name="FeedOne" subType="feedOne" factoryName="com.accenture.aspire:aspire-tools:2.0"> . . </component>
Component factories correspond to Bundles, i.e., actual physical JAR files that are dynamically loaded into Aspire.
Each JAR file can actually produce multiple different types of components, which correspond to different Java Classes that implement the Aspire Component interface. For example, the "aspire-rdbfeeder" bundle can create different components for pulling records from relational databases (RDB Feeder), creating sub-jobs based on an RDB query (RDB Sub Job Feeder) and extracting additional metadata from an RDB to be added to an existing job (RDB Row Extractor).
Sub Types are correlated to implementation classes within the component via the component's ComponentFactory.xml file.
Sub Types are desirable for many reasons. They reduce the number of JAR files required, they leverage third-party Jars incorporated into Bundle Jars for multiple component types, and they help make configuration (and coding) simpler.
The subType value required for each component can be found on the wiki page for that component.
Properties can be specified with ${propertyName} inside the system.xml file. These properties will be substituted when the configuration is loaded.
See Properties for more details on substituting properties.
Properties can be specified inside the <properties> tag inside the settings.xml file. All of these properties can be used for property substitution inside the settings.xml configuration file. See system.xml properties for more information.
Several standard Aspire property names are available to all configurations. These include:
Environment variables can used for property names. For example, ${JAVA_HOME}.
All Java system properties are also available. For example, ${user.home} will be the home directory for the user who started up Aspire.
You can also load properties in to Aspire from a Java properties file. The properties file would be of the form:
rdbDbName=research rdbUser=SYSTEM rdbPassword=hello my.rdb.password=helloAgain
Rather than directly loading the entire properties file (as these are quite often large and contain a large number of properties that that are irrelevant to Aspire), you configure Aspire to read just the properties you are interested in. These Java properties are then loaded to Aspire properties and the subsitution is performed as described above.
To load the desired properties, include an external tag in the properties section and then specified the filename in which the property is found.
For example, to load the my.rdb.password property from the file above, use:
<properties> <property name="crawlDataBase">data/crawler</property> <external name="my.rdb.password" filename="testdata/com.accenture.aspire.framework/Properties/test.properties"/> <external name="badReference" filename="testdata/com.accenture.aspire.framework/Properties/doesnot.exist"/> </properties>
NOTE: if the filename you give is not found, the Aspire property will be set to indicate this:
(unable to open external properties file testdata/com.accenture.aspire.framework/Properties/doesnot.exist)
Using the UI to load a configution file invokes an underlying Application servlet command start. If the user chooses to load a file named config/system.xml (by typing config/system.xml in the input box), the URL sent to the application is:
http://localhost:50505/aspire?cmd=start&config=config/system.xml
Other options that are not available via the UI are available using the command start. Using xml instead of config allows the user to specify an application xml fragment and load this configuration:
<application name="CSManager" config="com.searchtechnologies.appbundles:cs-manager:1.0-SNAPSHOT"> <properties> <property name="debug">true</property> <property name="managerExternalRDB">false</property> <property name="managerRDB">CSRDB</property> <property name="managerExternalJDBCUrl"></property> <property name="managerExternalJDBCDriverJar"></property> <property name="managerExternalJDBCUser"></property> <property name="managerExternalJDBCPassword"></property> </properties> </application>
The following URL loads the above configuration:
http://localhost:50505/aspire?cmd=start&xml=%3Capplication%20name=%22CSManager%22%20config=%22com.searchtechnologies.appbundles:cs-manager:1.0-SNAPSHOT%22%3E%3Cproperties%3E%3Cproperty%20name=%22debug%22%3Etrue%3C/property%3E%3Cproperty%20name=%22managerExternalRDB%22%3Efalse%3C/property%3E%3Cproperty%20name=%22managerRDB%22%3ECSRDB%3C/property%3E%3Cproperty%20name=%22managerExternalJDBCUrl%22%3E%3C/property%3E%3Cproperty%20name=%22managerExternalJDBCDriverJar%22%3E%3C/property%3E%3Cproperty%20name=%22managerExternalJDBCUser%22%3E%3C/property%3E%3Cproperty%20name=%22managerExternalJDBCPassword%22%3E%3C/property%3E%3C/properties%3E%3C/application%3E
Note that this is simply the URL encoded version of the xml:
< -> %3C " -> %22 > -> %3E <space> -> %20
You may also indicate that the new configuration should be written to the settings.xml file in the <autoStart> section. Use the autoStart flag for this:
http://localhost:50505/aspire?cmd=start&autoStart=true&xml=%3Capplication%20config=%22com.searchtechnologies.appbundles:cs-manager:1.0-SNAPSHOT%22%3E%3Cproperties%3E%3Cproperty%20name=%22debug%22%3Etrue%3C/property%3E%3Cproperty%20name=%22managerExternalRDB%22%3Efalse%3C/property%3E%3Cproperty%20name=%22managerRDB%22%3ECSRDB%3C/property%3E%3Cproperty%20name=%22managerExternalJDBCUrl%22%3E%3C/property%3E%3Cproperty%20name=%22managerExternalJDBCDriverJar%22%3E%3C/property%3E%3Cproperty%20name=%22managerExternalJDBCUser%22%3E%3C/property%3E%3Cproperty%20name=%22managerExternalJDBCPassword%22%3E%3C/property%3E%3C/properties%3E%3C/application%3E
Use the remove command to remove a component manager from the application's configuration:
http://localhost:50505/aspire?cmd=remove&name=/CWSManager
The name passed will be the name attribute from the file or app bundle loaded (or name from the component manager xml fragment if specified). When using remove you may also pass autoStart=false to remove the configuration from the settings file
At the top of the application XML file you can specify a name for the entire application, and some type flags, which identify the purpose of the configuration for the administration user interface:
<?xml version="1.0" encoding="UTF-8"?> <application name="MyName" typeFlags="feeder,sub-jobs"> . . . </application>
The name specified at the top of the application XML file is used for the following purposes:
Note that the name specified in the application.xml file is the default name. A new name can be specified in the System Administration user interface when the configuration file or app bundle is loaded.
The type flags in the system configuration file is specified as follows:
<application name="MyName" typeFlags="feeder,subjobs"> . . . </application>
The flags are optional and are used to specify how a configuration can be used to process jobs for the System Administration user interfaces.
The following flags are currently defined:
Although @typeFlags can be used as part of as part of application XML files, they are really designed to be used with Application Bundles (or App Bundles for short). App Bundles are units of functionality which can be made up of multiple pipeline managers and many components. App Bundles are specified with a system configuration file (as described on this wiki page) and can be bundled with other files into JAR files and deployed to Maven repositories.
The System Administration user interface can create routing tables, which are attached to jobs, and specify how they are routed from configuration to configuration (or, more typically, from App Bundle to App Bundle). The @typeFlags attribute is intended to provide enough information to the user interface so that these routing tables can be created.
Specifically: