Web Application Resource for Accessing Relational Entities

Figure 1. The User Admin Screen

Users can be created from the useradmin.vhtml page in the deployed application by simply typing the user name in the username field in the Manage Users section, selecting the primary group for the user and clicking on the InsertUser button. This will take you to the User Detail Screen

Figure 2. The User Details Screen

On the UserDetail screen you can add extra details for the user, change the primary group and set their password. You can also at this stage add additional group memberships for this user by clicking the AddMembership button.

When a user is a member of additional groups these will then be displayed on the User Detail screen. The groups to which a user belongs can be changed and updated by clicking the UpdateMembership button or deleted by clicking on the DeleteMembership button.

You can also search for users by entering in the username or partial username with % characters for wildcards in the username field in the Manage Users section and clicking the ShowUsers button. You can restrict the search to specific groups using the pull down box, or by selecting NONE search all groups for matching users. This will display a list of all matching users with a UserDetail button which will link to the User Detail Screen for that user.

Figure 3. The Groups Admin Screen

Groups can be created by entering a group name in the groupname field in the Manage Groups section field and clicking the InsertGroup button.

The show groups screen allows you to can edit the group name, list all members of a group or delete the group.

You can also search for groups by entering a partial groupname into the groupname field in the Manage Groups section with % characters for wildcards and clicking the ShowGroups button. This will link you straight to the Show Groups screen.

You should first configure a DataSource in your application server. The method of doing this is beyond the scope of this document but should be covered by the documentation for your application server. The minimum requirement is that the DataSource is made available to the WARFARE web application via the JNDI tree. This will nearly always involve installing the jar file containing the driver for the database you are connecting to into your application server. This may involve adding to the CLASSPATH in the startup script but most application severs have a better way of installing external libraries such as placing the jar files in to an ext directory or common/lib directory as in the case of Tomcat.

The web-application now needs to be configured to see the JNDI data source. The first place to configure this is in the web.xml file in the WEB-INF directory of the web application where you will need to add the resource references to the JNDI data source.

      <resource-ref>
      <description>
	Link up to the jdbc/pm data source
      </description>
	<res-ref-name>
	  jdbc/pm
	</res-ref-name>
	<res-type>
	  javax.sql.DataSource
	</res-type>
	<res-auth>
	  Container
	</res-auth>
      </resource-ref>
      

Finally the View Manager configuration needs to be made aware of the JNDI data source. This is done in the viewmanager.properties file. The connection name that is used to reference this data source in the views configuration is appended by a .log to specify a log file for this data source and by a .driver used to specify that this is a JNDI DataSource.

      pm.log=/var/tmp/pm.log
      pm.driver=JNDI
      

Application managed pools are orders of magnitude easier to set up which indicates how much simpler and less resilient they are but if you have no choice then its better than nothing. They are entirely configured within the viewmanager.properties file. You will need to specify the jdbc driver name, the URL to connect to the data base, username, password, a log file and the maximum size to allow the pool to grow to.

      pm.driver=org.postgresql.Driver
      pm.url=jdbc:postgresql://localhost:5432/pm
      pm.username=nomad
      pm.password=
      pm.log=/var/tmp/pm.log
      pm.maxpoolsize=10
      

You will also need to place the jar file containing the relevant driver into the WEB-INF/lib directory of the web application if you are planning on creating a completely self contained web application. Otherwise the driver will need to be added to the CLASSPATH of the server as with container managed connections.

A query template for the SQLDAO should be used to construct an appropriate SELECT statement to obtain the information you want from the database. <%prop ... %> tags should be used to substitute values in the select statement.

      select * from announcement
      where
      title like <%prop name="title" prefix="'" suffix="%'" default=""%>
      <%prop name="announcementid" prefix="and announcementid="%>
      order by posted desc
      

An update template can be used to to construct appropriate UPDATE, DELETE or INSERT statements to update information in the database.

      update announcement set
      title=<%prop name="title" prefix="'" suffix="'" default="none"%>,
      message=<%prop name="message" prefix="'" suffix="'" default="none"%>
      where 
      announcementid=<%prop name="announcementid"%>
      

A JMS Queue connection is configured within the viewmanager.properties. You will need to specify the context provider, context factory, the jms connection factory, a queue name, and whether to acknowledge the messages once displayed. The following example shows hte properties needed to connect to an OpenJMS queue.

      jmsqueue.provider=rmi://localhost:1099/
      jmsqueue.contextfactory=org.exolab.jms.jndi.InitialContextFactory
      jmsqueue.connectionfactory=JmsQueueConnectionFactory
      jmsqueue.queue=queue1
      jmsqueue.ack=true
      

If no query template is specified the raw text content of the message will be placed into a single field named messagedata and passed back to WARFARE.

If a template is specified it should be an XSLT template that can be applied to the text content of a message. The expected result of the transformation is a seriese of elements with any required information represented as attributes. Each element will be passed back to WARFARE as a separate DTO to support messages that may contain more than one data object.

      <?xml version="1.0"?>
      <xsl:stylesheet
	xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="1.0">
	<xsl:output method="xml" indent="yes"/>
	<xsl:template match="message">
	  <message sender="{sender}" data="{data}"/>
	</xsl:template>
      </xsl:stylesheet>
      

Update templates are used to construct the message to post. The template should be a normal WARFARE template and make use of <%prop ... > tags to insert values into the template. The output of the template will be posted as a TextMessage on to the specified Queue and need not be XML.

      <message>
	<sender><%prop name="VMUNAME"%></sender>
	<data><%prop name="message"%></data>
      </message>
      

A JMS Topic connection is configured within the viewmanager.properties. You will need to specify the context provider, context factory, the jms connection factory, a topic name, the name of the subscriber you wish to subscribe as and whether to acknowledge the messages once displayed. The following example shows hte properties needed to connect to an OpenJMS topic.

      jmstopic.provider=rmi://localhost:1099/
      jmstopic.contextfactory=org.exolab.jms.jndi.InitialContextFactory
      jmstopic.connectionfactory=JmsTopicConnectionFactory
      jmstopic.topic=topic1
      jmstopic.ack=true
      jmstopic.subscriber=sub1
      

If no query template is specified the raw text content of the message will be placed into a single field named messagedata and passed back to WARFARE.

If a template is specified it should be an XSLT template that can be applied to the text content of a message. The expected result of the transformation is a seriese of elements with any required information represented as attributes. Each element will be passed back to WARFARE as a separate DTO to support messages that may contain more than one data object.

      <?xml version="1.0"?>
      <xsl:stylesheet
	xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="1.0">
	<xsl:output method="xml" indent="yes"/>
	<xsl:template match="message">
	  <message sender="{sender}" data="{data}"/>
	</xsl:template>
      </xsl:stylesheet>
      

Update templates are used to construct the message to post. The template should be a normal WARFARE template and make use of <%prop ... > tags to insert values into the template. The output of the template will be posted as a TextMessage on to the specified Topic and need not be XML.

      <message>
	<sender><%prop name="VMUNAME"%></sender>
	<data><%prop name="message"%></data>
      </message>
      

Connections for the FileDAO is configured in the viewmanager.properties file. You need to specify the location to save the edited files back to on the server.

      files.savedir=webapps/warfare/WEB-INF/classes
      

When querying files the template parameter is not used to specify a template to be used. The template parameter instead specifies a field from the post data to be used as a file name to be edited. An example from the ViewManager application sets the daotemplate to getidtmpl for the EditGetIDTmpl view to used the value from the getidtmpl field as a file name to edit.

When saving files the filename will be taken from the post data and appended to the directory specified by the savedir property in the viewmanager.properties file. Templates are not made use of when saving a file.

The location of a Lucene index and other configuration options is specified in the viewmanager.properties file.

      lucene.indexdir=index
      lucene.identifier=articleid
      lucene.defaultfield=content
      lucene.fieldlist=departmentid,subject,precis
      lucene.indexonly=content
      

The template for a lucene search should be used to construct an appropriate query to be passed to a QueryParser. <%prop ... %> tags should be used to substitute values in the search statement.

<%prop name="departmentid" prefix="+departmentid:"%>
+(precis:<%prop name="query"%> content:<%prop name="query"%>
subject:<%prop name="query"%>)
      

When updating a Lucene index the field specified as the identifier is used to delete the record from the index. If the value of template is set to index the new document is added to the index. If the index does not exist yet it will be created by an attempt to add a record.

Connections for the XMLFileDAO is configured in the viewmanager.properties file. You need to specify the location of the file and the location to save the file back to.

xmlfile.filename=file:///usr/local/jakarta/webapps/warfare/test/address.xml
xmlfile.saveto=/usr/local/jakarta/webapps/warfare/test/address.xml
      

When Querying XML files the template specified is expected to be an XSLT. The template is first passed through the internal template parser to substitue any parameters. The XSLT should output a flat set of elements with all required values represented as attributes.

<xsl:stylesheet version="1.0"
       xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
  <xsl:output method="xml" version="1.0" indent="yes"
  standalone="yes" encoding="utf-8"/>

  <xsl:param name="search"><%prop name="Surname" default="Doe"%>
     </xsl:param>
  <xsl:template match="//Address">
  </xsl:template>
  <xsl:template match="//Address[Surname=$search]">
  <Address id="{@id}" FirstName="{FirstName}" Surname="{Surname}"
    Street="{Street}" PostCode="{PostCode}"/>
  </xsl:template>
  <xsl:template match="//Addresses">
  <Results>
  <xsl:apply-templates/>
  </Results>
  </xsl:template>
  
</xsl:stylesheet>
      

When Updating XML files the template specified is expected to be an XSLT. The template is first passed through the internal template parser to substitue any parameters.

<xsl:stylesheet version="1.0"
       xmlns:xsl="http://www.w3.org/1999/XSL/Transform"> 
  <xsl:output method="xml" version="1.0" indent="yes"
    standalone="yes" encoding="utf-8"/>

  <xsl:param name="search"><%prop name="id" default="2"%>
      </xsl:param>
  <xsl:template match="Addresses">
    <xsl:copy>
      <xsl:apply-templates/>
    </xsl:copy>
  </xsl:template>

  <xsl:template match="//Address">
    <xsl:copy-of select="."/>
  </xsl:template>

  <xsl:template match="//Address[@id=$search]">
    <Address id="{@id}">
      <FirstName><%prop name="FirstName" default="None"%></FirstName>
      <Surname><%prop name="Surname" default="None"%></Surname>
      <Street><%prop name="Street" default="None"%></Street>
      <xsl:copy-of select="Town"/>
      <xsl:copy-of select="County"/>
      <PostCode><%prop name="PostCode" default="None"%></PostCode>
    </Address>
  </xsl:template>

</xsl:stylesheet>
      

Figure 6. The View Search Screen

If you wish to maintain an existing view then you can enter a view name in the View Name field (using % characters as wildcards) and select the group and/or application that the view belongs to (or NONE if you don't know) and clicking on the ShowViews button. This will list all Views matching your search criteria. If you click the ShowViewDetail button next to the view that you are interested in you will be taken to the View Detail screen where you can maintain the view.

A view can be created by typing a new view name into the View Name field, selecting the group that the view should belong to and clicking the InsertView button. This will then take you to the View Detail screen.

Figure 7. The View Detail Screen

The View Detail screen presents you with a form containing all of the details of the view you are currently maintaining. You can alter the view name which is a short name used mainly to label buttons that link to this view. The long name is made available to the push templates and is used as a more informative descriptive title when displaying the view.

The pull down list of actions enables you to configure what action will be performed and the pulldown list of daoclasses allow you to select which class you will use to access your data. what type of view this is and how it will be processed. The text field labeled daotmpl should reference a filename relative to the WEB-INF/classes directory of your installed webapp or another location on the CLASSPATH. This file should contain the template to be passed to the DAO that will be accessing your data. A convenience method for loading this file into a form for you to edit is available if you click EditDAO.

The getidtmpl also references a file in the same way and can be edited using the EditGetIDTmpl. This file is usually used to contain SQL to obtain the primary key of a newly inserted record. This query should return one row with one field. The name of this field is pulled back into the parameter set and its value is available to subsequent chained views.

The connection field defines which datasource connection should be used to access any data for this view. You can then also select a layout from the Layout pull down menu to customise how this view is displayed. It is also possible to alter the group that owns this with the Group Name pull down menu.

The validationfunc field should specify a JavaScript function call to be called when the form for this view is submitted. e.g. validateThisView(this) which would call the validateThisView function in javascript and pass in the form which has been generated by this view.

Figure 8. The View Fields Screen

Fields can be configured from the View Detail Screen. Most view types do not need to have fields configured as the framework will by default render fields from a result set as a simple editable text field. If you wish to override this default (i.e. to display a field as read only) you should configure a field. Input views will always require fields to be configured to make use of the standard layouts as there is no results set for the framework to determine what to display.

Clicking on the ShowFields button on the View Details screen will list all of the fields that have been configured for this view. Clicking on the InsertField button will create a new field for you to configure for this view and then display the list of all Fields. The Show Fields screen allows you to alter the name of the field that this configuration applies to and the Label that should be displayed alongside the field. You can also configure the number of lines you want the text box to be (-1 creates the text box as a password field), the width of the text box and also whether the results should be displayed read-only or hidden. You can also pick a pull down menu to be used when displaying this field. Default values for the fields can also be input into this screen.

Once you have configured a field appropriately you should click UpdateField to save the configuration. If you no longer require a field to be configured then you can click the DeleteField button to remove that field from the view configuration.

Figure 9. The View Links Screen

Links are administrated in the same way as Fields,clicking on the ShowLinks button will show any links for this view. Clicking InsertLink will create a new link and then display the list of all links. The Show Links screen allows you to select from a pull down list the view that this link will link to. The sequence of the view this is primarily used to determine the order of buttons linking views when displayed on screen. Most importantly you can select from a pull down list which type of link you would like this link to be.

A Normal Link will be displayed as a button on screen when displaying this view. When clicked the button will submit the entire contents of this view as input variables to the view that is linked to. This enables you to find related records in another view i.e. to obtain a list of all invoices for a single client when you are looking at a clients record.

An In-Line link performs in a very similar way in that the details from one view are fed as input parameters to the view that is linked to but with an in-line link the results are displayed on the same page instead of rendered on a separate page after clicking a button.

A chained link is completely different in that generally only the input parameters from the current view are passed on to the next view in the chain. Any results from executing the getidtmpl will also be passed. This will also prevent the current view from being displayed unless it fails to process. Only the view at the end of a chain is displayed. An example of using chained views would be to chain a Display Details View after a view which has inserted a record. The getidtmpl can determine the primary key of the record that has just been inserted and pass this onto a query view to retrieve the inserted record and display it for further editing.

Once you have edited the link you are interested in and you are happy with it you can click on UpdateLink to save the changes that you have made. If you would like to discard this link then you can click on DeleteLink to delete the link.

The properties here are available to most templates as they are generated and fed in from the front end.

These properties are generally available to page templates in layouts. The page template is used to provide a consistent wrapper for view presentation.

Server templates are used to provide feedback to the user on what a view has performed. In the case of update views they can be used to show how many rows have been updated, the saved values of any inserted records. If any view failed server templates can be used to display any error codes and the SQL that the server attempted to execute.

Record templates have a whole host of parameters to represent each field that is returned as part of the results set. These properties are accessed for each field by specifying the field followed by a . and the name of the property. You can also position any sub-views using the subview property.

Some additional parameters are available to vhtml templates to incorporate various extra views.