Data Sources

Requires Platform 4.2+; Requires Data Framework Plug-in top

A data source is an object capable of supplying objects and data sets based on query strings.

The data framework plugin currently ships with two data sources, the document data source and the object data source. See the "Supplied Tags" section for complete information.

In addition, developers may create their own data sources, see "Creating a Data Source" for complete information.

Supplied Tags

Nexaweb 4.2.x provides the following pre-built data source tags:

<documentDataSource> - based on XML docs and XPath for queries.
<objectDataSource> - based on object hierarchies and OGNL.

documentDataSource Tag

The documentDataSource tag provides you with a data source that wraps an XML document and uses XPath to serve data to the binding target. You can configure this dataSource to automatically refresh data at the binding target when the XML document changes as follows:

An attribute available on the XML document changes
The structure of the XML document changes

The documentDataSource refreshes data by re-running stored queries.

The documentDataSource tag includes the following attributes:

Attribute	Description	Required/Optional
source	A path to the location of the data. Use any of the following formats: Absolute HTTP URL (static page or dynamic page that writes out a document to the output stream). For example, http://localhost:9090/myPage Relative HTTP URL (static page or dynamic page that writes out a document to the output stream). For example, ../../mypage, relative to where this page was loaded. Container path, document://myDoc, where myDoc is the name of an existing registered document. Container path with method call. For example, mco://myMco.getMyDocument(). The method must return a com.nexaweb.xml.Document object wrapped by the datasource. If myMco is null or the result of the method chain is null, Nexaweb throws a DataAccessException. The default is null. Note: If you do not specify a source, Nexaweb expects the source to be set programmatically later on.	Optional
id	Uniquely identifies the data source using a system wide unique value.	Required
documentName	Registers the source document retrieved from the source in the DocumentRegistry. This attribute essentially translates into a loadDocumentFromUrl(sourceUrl, documentName) call. If the documentDataSource tag does not specify a source, the documentName attribute has no effect. To set the source and register the document in the DocumentRegistry programmatically, use one of the following API methods: setSource(Document doc, String documentName) loadDocumentFromUrl(String sourceUrl, String documentName) If a document with the same name is already registered under the documentName name, these methods unregister it.	Optional
refreshOnAttributeChange	Specifies whether to refresh the datasource when attribute change events fire on any element in the source document. Values: true \| false Default: true	Optional
refreshOnStructureChange	Specifies whether to refresh the datasource when structure change events fire on any element in the source document. Values: true \| false Default: true	Optional

The following table describes the methods included in the documentDataSource API:

Method	Description
refresh()	Forces all one-way bindings to re-resolve.
loadDocumentFromUrl(String sourceUrl)	Replaces the old document with the new one within a DocumentDataSource instance.
loadDocumentFromUrl(String sourceUrl,String documentName)	Replaces the old document with the new one and registers the new one in the DocumentRegistry. If a document with the same name was already registered, Nexaweb unregisters it first. If refreshOnStructureChange is set to true, Nexaweb calls refresh() automatically.
setSource(Document newDoc)	Sets the source for the DocumentDataSource to be newSourceDocument. If refreshOnStructureChange is set to true, Nexaweb calls refresh() automatically.
setSource(Document newDoc, String documentName)	Sets the source Document to the new value and registers it in the DocumentRegistry under the specified name. If a document with the same name was already registered, Nexaweb unregisters it first. If refreshOnStructureChange is set to true, Nexaweb calls refresh() automatically.
getDocument()	Returns the source Document of a DocumentDataSource instance.
setRefreshOnAttributeChange(boolean)	Sets the value of the refreshOnAttributeChange in a DocumentDataSource instance.
setRefreshOnStructureChange(boolean)	Sets the value of the refreshOnStructureChange in a DocumentDataSource instance.
getRefreshOnAttributeChange()	Returns the boolean value of the refreshOnAttributeChange.
getRefreshOnStructureChange()	Returns the boolean value of the refreshOnStructureChange.

ObjectDataSource Tag

The ObjectDataSource tag wraps Java objects that represent data that you want to access. You can then access that data using Object Graph Navigation Language (OGNL), a query language for accessing data from Java objects. In addition to using the ObjectDataSource tag as provided, you can extend it. For example, you can use ObjectDataSource as provided or by extending it to wrap the results of a WebServices call.

The ObjectDataSource tag includes the following attributes:

Attribute	Description	Required/Optional
source	Specifies the path to the object to wrap. Specify path using one of the following formats: Absolute HTTP URL. Path to a page that writes out a serialized object to the output stream. The object's class must be on the client's classpath. For example, http://host/myapp/getObject.jsp. Relative HTTP URL. For example: /getObject.jsp (relative to the root context) or getObject.jsp (relative to the page that loaded the datasource). Container path. For example: mco://myMco. (If myMco does not exist, Nexaweb throws DataAccessException.) Container path with a method call. For example: mco://myMco.getFoo().getBar(). The method chain must return an object and the datasource wraps that object. If myMco is null or the result of the method chain is null, Nexaweb throws a DataAccessException.	Optional
id	Uniquely identifies the data source using a system wide unique value.	Required
refreshOnPropertyChange	Specifies whether to refresh the datasource when property change events fire on the source object. To enable datasource refresh, you must: Set this attribute to true Include in the source object the following public methods for adding\removing PropertyChangeListener instances: public void addPropertyChangeListener(PropertyChangeListener) public void removePropertyChangeListener(PropertyChangeListener) Values: true \| false Default: true	Optional

The following table describes the methods included in the ObjectDataSource API

Method	Description
refresh()	Forces all one-way bindings to re-resolve.
loadObjectFromUrl(String sourceUrl)	Retrieves the object from the sourceUrl and sets it as the new source.
setSource(Object newSource)	Changes the source of the ObjectDataSource to be the "newSource" object.
getObject()	Returns the source object of this DataSource
setRefreshOnPropertyChange(boolean)	Sets the refreshOnPropertyChange attribute.
getRefreshOnPropertyChange()	Returns the value of the refreshOnPropertyChange attribute (boolean).

Object Graph Navigation Language (OGNL)

OGNL is an expression language for getting and setting properties of JAVA objects. You use the same expression for both getting and setting the value of a property.

Nexaweb provides a JDK 1.1 compliant version of OGNL. This means that you can use only OGNL grammar and implementation classes compliant with JDK 1.1. If you know that your application runs on JDK 1.2 or higher compliant browers only, you can replace Nexaweb's version of OGNL with your own OGNL version and use all grammar and implementation classes that it supports. For detailed information on OGNL, see opensymphony.com/ognl/.

Syntax

Nexaweb provides the following method for getting property values with OGNL expressions:

Ognl.getValue( String expression, Object root )

where: String expression represents a OGNL query string, and
Object root represents the root of your object tree (similar to a context in XPath).

Query String Expression Examples

In these examples, the root object has an integer instance field called, bar, and a Vector instance field called, myVector. With private fields, OGNL automatically looks for getX() and setX() methods.

Note: These example expressions demonstrate a small subset of the OGNL functionality; the full grammar supports much more.

Expression	Description
"bar	Returns the value of the bar variable.
"bar=10"	Sets the variable to 10.
"myVector.addElement(new Integer( bar ))"	Adds an integer value of bar to the myVector.
"myVector.{delegate()}"	Calls delegate() method on each element contained in myVector and returns a new list that contains the return values of those calls.
"myVector.size().(#this > 100? 2*#this : 20+#this)"	the size of the Vector gets bound to #this variable (#this always refers to the current value of an OGNL expression), then the expression that follows gets evaluated returning one of the outcomes.

Creating a Data Source

As part of the data binding framework, Nexaweb provides you with the ability to implement your own custom data sources. For example, you can implement your own functionality to load data from a database or to provide access to a custom set of objects. In order to implement the functionality of a data source, you must implement the required interface (com.nexaweb.plugin.data.datasource.DataSource) as defined in the API section.

Nexaweb ships with the predefined dataSource tag. You can use this tag to serve data to an interface that you implement by specifying the implementation's class as an attribute of the dataSource tag.

Attribute	Description	Required/Optional
id	Uniquely identifies the data source; developer should take care to specify a system wide unique value.	Required
class	Identifies the implementation of the data source.	Required

In addition, developers may elect to create their own data source tag definitions.

Query Strings/Select Statements

Each data source must understand a query string that indicates the location within the data source of the data to retrieve. For example, the documentDataSource will use XPath query strings to retrieve nodes from an XML document. It is up to the data source implementor to define the syntax for retrieving data.

Example

The following example shows a custom data source tag that loads hibernate objects and uses a custom tag handler for the hibernateDataSource tag. The data source is based on hibernate.

<hibenateDataSource id="customers" sourceUrl="hibernateServlet"/>