Busdataisland

Maintains the transaction object. It uses SOAP Messages to communicate with the Web Gateway.

Syntax

HTML	<div cordysType="wcp.library.data.BusDataIsland id= "busdataislandID" > ... </div>

where, busdataislandID denotes the unique identifier of the component.

The busdataisland fetches data from the backend by sending and receiving SOAP Messages. The functionality of the component can be split into two parts. One part of the functionality physically interacts with the Web server, while the other maintains the transactional state of the XML objects.

To interact with the Web Server, parameters such as the URL of the Web gateway and the receiver to which the response is sent can be specified. The busdataisland uses methods like reset and sendAndWait to send the request to the back end and receive the transactional objects. Transactional objects are XML responses from the backend and are usually referred as "tuples".

If the busdataisland receives a SOAP message, the content inside it is made available through the data property. A series of events are raised to enable pages that use this component to respond to the new content available from the backend.

The process flow of the busdataisland is explained below:

It creates a method call for the appropriate request defined. This includes filling in the parameters of the method.
It sends the request to the Web Server and receives the response data.
It fires events for each request sent and received and for any error generated.

To dynamically add and initialize this component, you can use the initializeHTMLElements or addType methods of the Application object.

The properties and methods defined for the busdataisland component are as follows:

Table 1. List of Attributes

Attribute	Property	Description
async	async	Boolean that specifies whether the XML interaction with the Web Server is asynchronous. The value of this property is the async property set in the send method of the XMLHTTP object. The possible values are: true: Default. Interaction with Web server is asynchronous. false: Interaction with the Web server is synchronous. The next request to the Web server will be processed only after the current request is processed.
automatic	automatic	Boolean that specifies whether the request is sent to the Web server automatically once the page is loaded. The possible values are: true: Default. Request is sent to the Web server once the document is loaded. false: Request is sent to the Web server on an explicit call of the reset method.
data	data	Object that denotes the content present in the response received from the Web server on a request.
iteratorSize	iteratorSize	Integer that denotes the number of tuples that can be retrieved from the back end in a read operation. If this property is not mentioned then it retrieves all the records returned by the request.
parameters	parameters	Array that contains all the parameters that can be specified on the URL to which SOAP Messages are posted.
request	request	Object that contains SOAP Message to be send to the back end.
requestHeaders	requestHeaders	Bus Data Island exposes this property for setting the custom headers that can be part of XMLHTTP. The usage of this property is as follows: requestHeaders['soap-action'] = <URL> requestHeaders['myheader'] = <header value> If this property is set in the System component, too, then the value specified for Bus Data Island takes precedence.
updateMethod	updateMethod	String that denotes the tag name of the update request that can be sent to the back end. By default, this is 'Update'.
updateNamespace	updateNamespace	String that denotes the namespace of the update request that can be sent to the back end. If this property is not set, the namespace for update method will be taken from the response or the request message of the busdataisland.

Table 2. List of Methods

Method	Description
add(businessElement, source)	Adds a new tuple to the data in the BusDataIsland. businessElement denotes the object containing the business element that is to be added. source is an optional parameter that refers to the element that called this function. It could be the ID of the buscontrol or the busdataisland itself.
appendUpdate(soapBody)	Appends the update request to the SOAP Body that is to be sent to the back end. It takes SOAP Body as an input. Update request will be prepared for all the tuples that have been modified (tuples with a sync_id attribute).
clear	Removes the current data from the BusDataIsland and notifies its listeners by firing ondatacleared event.
create	Creates a new tuple.
edit(businessElement, source)	Returns the appropriate business element for editing. businessElement denotes the business element that is to be edited (updated). source is an optional parameter that refers to the element that called this method, which can be the ID of the buscontrol or the busdataisland itself.
getNextDataSet	Gets the next dataset from the back end. This is specified at the cursor position for a given iteratorSize.
hasMoreDataSets	Returns a boolean that indicates if there are data to be retrieved from the back end in a read operation. This method will work only when there is a cursor property set.
isModified	Returns a Boolean that denotes whether the tuple is modified. This property is checked before calling the synchronize method of the busdataisland, which updates all the changed tuples to the back end. This property is READ-ONLY.
memorize(businessElement, source)	Starts recording changes on the business element from the moment this method is called. businessElement points to the object containing the data. source is an optional parameter that refers to the ID of the element that called this method. The current status of the business element is supposed to be the current state of the business element in the server as well.
notifyModifiedTuple	Tracks when a tuple is modified.
reset	Retrieves new data from the back end for a specified request.
remove(businessElement, source)	Marks a tuple for deletion. businesElement is an object containing the name of the business element to be removed. source is an optional parameter that refers to the ID of the element that called this function.
sendAndWait	Sends an XML document to the back end, waits for the response and handles when the response is received.
synchronize	Sends an update request to the server. Call this method after adding, updating, or deleting data in the busdataisland. The response XML will be included in the data property of the busdataisland.
unedit(businessElement, source)	Reverts back the changes made to the tuple. It changes the tuple so that no update takes place for it on synchronization with the back end. businessElement denotes the actual business element inside the tuple source is an optional parameter that refers to the ID of the element that called this function.

Remarks

The create method is invoked for creating a new empty tuple in the existing format, while the add method is invoked for attaching a user-defined tuple, which can be in any format.

The busdataisland also listens to the application's onselect event (Occurs when an application is selected), and looks for a <request> or a <response> tag inside the Application Definition. If they are found, each of them is executed sequentially. If a <request> tag is found, its data is set to the request property of the BDI and the reset method is called. For a <response> tag, the putData method of the BDI is called which sets the data property of the busdataisland and fires the necessary events. These events can be caught by other components such as buscontrol that use the response for rendering.

Following is an example of how a request can be passed through an application definition:

<Application>
    <id>applicationID</id>
    <description>Application Description</description>
    <caption>Application Caption</caption>
    <url>page url</url>
    <frame>FrameID</frame>
    <data>
        <request BusDataIsland="diEmployees">
            <!-- ID of the BDI should be given, so BDI ONLY for its requests -->
            <SOAP:Envelope>
                <SOAP:Body>
                    <GetEmployee xmlns="http://schemas.cordys.com/1.0/demo/northwind">
                        <EmployeeID dt="i4">1</EmployeeID>
                    </GetEmployee>
                </SOAP:Body>
            </SOAP:Envelope>
        </request>
    </data>
</Application>

The following are the Events exposed in the busdataisland.

Table 3. List of Events

Event	Description
ondatacleared	Fires after the clear method removes the current data from the busdataisland.
ondatacompleted	Fires when the SOAP Message that was received from the XMLHTTP object has been completely handled by the busdataisland.
onhttperror	Fires when the XMLHTTP did not receive XML from the Gateway.
onrequest	Fires when a SOAP Message is sent using XMLHTTP to the Gateway.
onresponse	Fires when the XMLHTTP receives a SOAP response from the Gateway.
onsoapfault	Fires when the SOAP Message received contains a back end error.
ontuplemodified	Fires when a tuple has been modified in the local document.
ontuplereceived	Fires for each tuple in a data received from back end that has noidattribute.
ontuplesynchronize	Fires when the body block is appended to the data.
ontuplesynchronized	Fires for each tuple in an update response received from the back end that has async_idattribute. A tuple with async_iddenotes that the tuple has been modified.

The onsoapfault event that will be fired by this component is shown through a generic HTML page, which just shows the fault description. More information about this feature can be found at Customizing SOAP Fault.

It is also possible to spy the messages sent or received from the Busdataisland. This is made possible by setting the property debug to true in the application component. Once set to true, the messages sent from and to the Busdataisland can be displayed in the debugger window. The message sent is displayed, and can be modified. Once modified, the modified message is taken as the request or response and is sent or received.

Note:

Sometimes, an empty HTTP response is received from the server. Such empty HTTP responses are also received when there are errors during the execution of code at the server side. Such responses are ignored by the busdataisland. This is specific to Windows NT.

Example

The following code is an example of a busdataisland which refers to the GetObject method.

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
	<html >
		<head>
			<script src="/cordys/wcp/application.js" ></script>
			<script type="text/javascript" >
				function getData()
				{
					var request = cordys.cloneXMLDocument(constructor.XMLDocument);
					cordys.selectXMLNode(request,".//*[local-name()='EmployeeID']").text = document.getElementById("txtEmployeeID").value;
					bdiEmployees.request = request;
					bdiEmployees.reset();
				}
				function setData()
				{
					var response = cordys.selectXMLNode(bdiEmployees.data,".//*[local-name()='Employees']");
					if (response)
					{
						document.getElementById("txtFirstName").value =  cordys.getTextContent(cordys.selectXMLNode(response,".//*[local-name()='FirstName']"));
						document.getElementById("txtLastName").value =  cordys.getTextContent(cordys.selectXMLNode(response,".//*[local-name()='LastName']"));
						document.getElementById("txtTitleOfCourtesy").value =  cordys.getTextContent(cordys.selectXMLNode ( response,".//*[local-name()='TitleOfCourtesy']"));
						document.getElementById("txtTitle").value = cordys.getTextContent( cordys.selectXMLNode ( response,".//*[local-name()='Title']"));
						document.getElementById("txtBirthDate").value =  cordys.getTextContent(cordys.selectXMLNode ( response,".//*[local-name()='BirthDate']"));
						document.getElementById("txtHireDate").value = cordys.getTextContent(cordys.selectXMLNode( response,".//*[local-name()='HireDate']"));
					}
					else application.notify("Record not found !");
				}
			</script>
		</head>
	<script type ="cordys/xml" id="constructor" >
	<SOAP:Envelope xmlns:SOAP="http://schemas.xmlsoap.org/soap/envelope/">
		<SOAP:Body>
			<GetEmployeesObject xmlns="http://schemas.cordys.com/DemoWebServices">
			<EmployeeID>2</EmployeeID>
		</GetEmployeesObject>
		</SOAP:Body>
	</SOAP:Envelope>
	</script>
	<body>
		<div cordysType="wcp.library.data.BusDataIsland "  id="bdiEmployees"    async="false"    automatic="false"    ondatacompleted="setData()" ></div>
		<table>
			<tr><td><h4>Employees Data</h4></td></tr>
			<tr>
				<td>EmployeeID</td>
				<td><input type="text" style="width:150px" id="txtEmployeeID" ></td>
				<td><button class="medium" style="width:100px" onclick="getData()" >Get Data</button></td>
			</tr>
			<tr>
				<td>Title of Courtesy</td>
				<td><input type="text" style="width:150px" id="txtTitleOfCourtesy" ></td>
			</tr>
			<tr>
				<td>First Name</td>
				<td><input type="text" style="width:150px" id="txtFirstName" ></td>
			</tr>
			<tr>
				<td>Last Name</td>
				<td><input type="text" style="width:150px" id="txtLastName" ></td>
			</tr>
			<tr>
				<td>Title</td>
				<td><input type="text" style="width:150px" id="txtTitle" ></td>
			</tr>
			<tr>
				<td>Birth Date</td>
				<td><input type="text" style="width:150px" id="txtBirthDate" ></td>
			</tr>
			<tr>
				<td>Hire Date</td>
				<td><input type="text" style="width:150px" id="txtHireDate" ></td>
			</tr>
		</table>
	</body>
</html>