Value sources are implementations of the com.netspective.commons.value.ValueSource interface that allows dynamic data to be included in XML without creating a programming language inside XML. There are many locations in the Project where value sources are used: configuration variables, forms/dialogs, form fields, form conditionals, SQL statements, and SQL bind parameters. Value sources allow common business logic and business values to be stored in shareable instance and then used either in XML or Java files where necessary. Value sources can be either single or multiple (list context) and are used anywhere dynamic data is required. The format of a value source is similar to a URL (name:params).
The best way to learn about Value Sources is to consider some examples. Although value sources are used throughout the NEF, some of the most common usage patterns will occur in the Sparx presentation layer (like Navigation pages and Dialogs) so the following examples focus on that layer.
<dialog heading="session:myHeading"><field type="text" name="text-field" caption="staticCaption" default="request:varname"/>
<field type="integer" name="int-field" caption="request:myCaption" default="my-rule:some-value"/>
<field type="select" name="files" caption="Files" choices="filesystem-entries:/home/all"/>
</dialog> <navigation-tree name="abc"> <page name="def" caption="something" heading="session:someVar"/>
| | A dialog specification is defined to have a heading which will be dynamically generated at run-time from the value of the 'myHeading' session attribute. |
| | The text field will have a static caption, but its default value will come from a request parameter called 'varname'. |
| | In the integer field example, the caption and default will both be dynamic and the default value will actually come from a class that has been registered as 'my-rule'. |
| | In the select field example, this select field fills its choices with the files contained in the directory /home/all. |
 | In the navigation-tree page example, the caption is static but the heading attribute will be dynamically retrieved from a session variable called someVar. |
The NEF ships with many built-in value sources and you can create as many value sources as you need on your own. To view a list of all of the value sources available to your project (including all built-in value sources and your own custom value sources) just go to Console's -> page.
Since values are specified as static text (like within an XML file) but their content is actually dynamic, a Value Context is necessary to determine what the value of any value source will be at the time when it's called. For example, a static value source (described below) whose value never changes doesn't really care what context it's in: it's very will remain the same at all time. However, if you have a value source that is specified as "request:XXX" (the value of a request parameter called XXX) then it's important to have the value context know the Servlet request object at the time. Put another way, the Value Context is sort of an Environment within which a value is evaluated and returned.
- ValueContext interface
The com.netspective.commons.value.ValueContext interface is used to define the common methods required in all value contexts.
- TabularReportValueContext class
The com.netspective.commons.report.tabular.TabularReportValueContext class
- DialogContext class
The com.netspective.sparx.form.DialogContext class
- NavigationContext class
The com.netspective.navigate.NavigationContext class
The simplest value source is known as the static value source – which is simply a wrapper for the Java String object. So, if an attribute accepts a value source, you can always supply a static string and it will be wrapped inside a com.netspective.commons.value.source.StaticValueSource class. For example, the following examples all produce the same results:
<field type="text" caption="ABC"/> <field type="text" caption="static:ABC"/> <field type="text" caption="string:ABC"/> <field type="text" caption=”com.netspective.commons.value.source.StaticValueSource:ABC"/>
The com.netspective.commons.value.ValueSources factory class is responsible for parsing value source specifications. The "name" portion of the value source refers to either a value source identifier (like "session" or "request") or the full name of a class that exists in your classpath. You can escape a value source by using the \ character in front of the : token. For example, if you’d like to create a string called "name:params" and not have it treated as a value source, use "name\:params". Given a string of the format name:params, Sparx performs the following steps during the parse:
Using the "name" portion of the declaration, check the com.netspective.commons.value.ValueSources factory class in the to see if it’s a built-in value source or has been registered separately by an application (it doesn’t matter if it’s a built-in source or one that you create and register yourself -- every value source is treated the same way).
If the value source identifier ("name") is found in the com.netspective.commons.value.ValueSources factory, get the associated class name (which must be a class that implements the com.netspective.commons.value.ValueSource interface). We will refer to this as the Value Source Class.
If the value source identifier is not found in com.netspective.commons.value.ValueSources factory check to see if "name" is a class name by using the Class.forName("name") method. Assuming a class is found, we will refer to this as the Value Source Class.
Using the Value Source Class found from either step 2 or step 3, check to see if there is already an instance created for the class. If there is an existing instance, use that instance (so that value sources may be shared). If there is no existing instance, instantiate a new object by constructing the Value Source Class, calling its initializeSource() method and passing in the "params" portion of the value source declaration and cache the object for future use.
The following example shows how you can use the value-source tag create your own value sources and register them so that the NEF will be able to use them. Assuming that you have created a class called MyValueSource that implements the com.netspective.commons.value.ValueSource interface and have placed your class in the package my.value.source you can use the following declaration in your APP_ROOT/WEB-INF/sparx/project.xml file.
<project>
<value-source class="my.value.source.MyValueSource"/>