DXF End-to-End Example

From wiki.searchtechnologies.com
Jump to: navigation, search

For Information on Aspire 3.1 Click Here

This examples shows the DXF template, how this template will be displayed in the user interface as an HTML form, and then the XML file which is produced after the user fills out the form and clicks "Submit".

Why do you need DXF?

Determine exactly why you need to use DXF. This will determine what file you will need to create or edit.

  1. I am Creating an Application Bundle - If you want to specify properties to be edited by the administrator when your application is installed, you will need to edit the DXF Template stored in config/application-dxf.xml.
  2. I am Creating a Connector - If you are creating a connector which will be working with the Aspire Corporate Wide Search connector framework, you will likely need to create a DXF template stored in web/components/{component-path}/dxf.xml.
    • This file will be used to specify the properties that are required for every content source which is submitted to your connector.
    • If you bundle your connector as an AppBundle (which is typical, so it can be shared through Maven Repositories), then you'll also need to create the same config/application-dxf.xml file described above.
  3. I am Creating a New Component - [Anticipated for Future Release]. At some point, every component will also have a dxf.xml file for editing the configuration properties for that component. This DXF template will be stored in your component JAR file, under resources/{implementation-class}/dxf.xml.
  4. I want to use DXF for something else - This is certainly possible, but not well documented at this stage. The entry point will be the DXFMain class (found in aspire-framework), which takes the dxf.xml template plus an XML of your initialization data and produces two JSON objects: one for the template and one for the initialization data. This can then be used by a JavaScript program, dxf.js, found inside aspire-application to display the form to the end user and gather up the resulting XML form data.

The Template

In the template, tags strictly for DXF purposes are prefixed with "dxf:". All other tags are copied to output when the form is submitted.

In the example below, all tags which start with <dxf:...> are special tags which control how the user interface is displayed. The tags <properties> and <managerExternalRDB> and similar are application-specific tags which are used to structure the metadata when the resulting XML data is produced.

Example DXF Template:

 <dxf:template version="1.0" xmlns:dxf="http://www.searchtechnologies.com/DXF/2011">
   <properties>	
     <managerExternalRDB display="Use external RDB?" type="boolean">
       <dxf:help>Check this box if the CS Manager should be using an external relational database to hold data for the CS administration user interface. Otherwise, it will use an embedded Apache Derby database inside the CS Manager itself.</dxf:help>
     </managerExternalRDB>
     <managerRDB display="Internal RDB Component Name" type="String">
       <dxf:help>The name of the Aspire component to use for the internal database. Should always be CSRDB when using the internal RDB, or CSExternalRDBConnector when using the external RDB.</dxf:help>
     </managerRDB>
     <managerExternalJDBCUrl display="JDBC URL" type="string">
       <dxf:help>If using an external RDB to hold admin UI information, this is the JDBC URL which identifies the server and database of the server to use. Something like "jdbc:oracle:thin:neptune.acme.com:1521:T10A" for Oracle, "jdbc:mysql://localhost/test" for My SQL, or "jdbc:sqlserver://localhost\SQLEXPRESS:1433" for SQL Server.</dxf:help>
     </managerExternalJDBCUrl>
     <managerExternalJDBCDriverJar display="JDBC driver" type="string">
       <dxf:help>The jar file inside the Aspire distribution which contains the JDBC driver for your external database. This will typically be a file in the lib directory, such as "lib/ojdbc6.jar" (Oracle), "lib/mysql-connector-java.jar" (My SQL), or "lib/sqljdbc4.jar" (SQL Server).</dxf:help>
     </managerExternalJDBCDriverJar>
     <managerExternalJDBCUser display="JDBC user" type="string">
       <dxf:help>The user name that will be used to log into the external database, if one is configured.</dxf:help>
     </managerExternalJDBCUser>
     <managerExternalJDBCPassword display="JDBC password" type="string">
       <dxf:help>The password that will be used to log into the external database, if one is configured.</dxf:help>
     </managerExternalJDBCPassword>
     <debug display="Debug" type="boolean">
       <dxf:help>Turn on debugging. Debug messages will be written to the log files.</dxf:help>
     </debug>
   </properties>
 </dxf:template>

User Interface Form

When shown in a browser, the user interface for the dxf.xml template shown above will look like this:

EditServerDxf.png

Note that each ? icon is a mouse-over pop-up help page which will display the contents of the <dxf:help> tag for each input element (admittedly, the help expressed above is not wonderful, it is left as an exercise for the reader to come up with better help text).

XML Output

Once the user has filled out the information in the form and has clicked on "Submit" (or "Save"), DXF will produce the following XML as output:

   <properties>	
     <managerExternalRDB>true</managerExternalRDB>
     <managerRDB></managerRDB>
     <managerExternalJDBCUr>jdbc:sqlserver://localhost\SQLEXPRESS:1433</managerExternalJDBCUrl>
     <managerExternalJDBCDriverJar>lib/sqljdbc4.jar</managerExternalJDBCDriverJar>
     <managerExternalJDBCUser>test</managerExternalJDBCUser>
     <managerExternalJDBCPassword>test</managerExternalJDBCPassword>
     <debug>true</debug>
   </properties>

Then What Happens?

What happens next depends on the application. If installing a new application, the admin UI will take the XML and write it as properties along with the application to the admin RESTful interface. The properties are then stored in the settings.xml file as part of the application's auto-start properties.

If the DXF is used to configure a content source for a particular connector, the XML is written to a database BLOB. When the content source is then crawled, the XML will be provided to the connector so that it knows what to crawl and has all of the other information (user name, password, include patterns, exclude patterns, etc.) it needs to execute the crawl.

Finally, if the DXF is used to configure an individual Aspire component (anticipated for a future release), then the resulting XML will be sent to the component's component factory, will will shut down the old version of the component and then restart the component with the new configuration.