Variable Builder

Variable Builder

In this topic ...

Quick Tips
Specifying Inputs
Accessing Variable Values
Using Alternative APIs for DOM and JDOM Variables
Using Schemas to Provide Additional Data Types
Related Topics ...

How to Use the Data Page Builder
How to Use the Simple Schema Generator Builder

Use a Variable builder call to store temporary or persistent data in a model . Other builders within your model can use a variable's value as a data source or modify or process variable content in any way. Variables are not accessible to builders outside of the model in which they reside. To expose a variable's value to a Linked Model create accessor methods that get and set any variable values.

Quick Tips

Use an easy to understand name when naming a variable. This name is displayed in the tree-based source lists of many other builder edit pages. Using a concise name facilitates locating a variable within a tree.

Specifying Inputs

The Variable builder takes the inputs described in the table below. For help on inputs common to many or all builders such as those in the Properties and HTML Attributes input groups, see "Using the Builder Call Editor."

Input Name Description
Name Enter a name for this builder call. The Designer displays this name in the Builder Call List.
Type Enter the data type for the value that the variable will hold from one of the following choices:

String

Integer

Double

Float

Long

Boolean

XMLData

Object

In addition to these standard data types, we can also declare variables to be of a type defined in a schema that you have added to the model with the Schema builder. For more information about assigning data types defined in a schema, see " Using Schemas to Provide Additional Data Types".
Schemas that define many elements could cause an "Out of memory" error due to the fact that those elements need to be displayed as possible types by the Reference Chooser.
(Optional) Namespace Enter the URL to the schema definition. If the schema referenced in the Schema builder call includes an xmlns declaration, that value is used to prepopulate this input.
(Optional) Namespace prefix Enter a string that will be prepended to element names in the XML structure. For example, you could differentiate between two Address types by using a namespace prefix; perhaps ba for a billing address and sa for a shipping address.
<sa:Sample xmlns:sa="http://bowstreet.com/2002/03/datamapper">
   <sa:firstName>Sample firstName</sa:firstName>
   <sa:lastName>Sample lastName</sa:lastName>
   <sa:address1>Sample address1</sa:address1>
   <sa:address2>Sample address2</sa:address2>
   <sa:city>Sample city</sa:city>
   <sa:state>Sample state</sa:state>
   <sa:zip>Sample zip</sa:zip>
   <sa:phone>Sample phone</sa:phone>
   <sa:email>Sample email</sa:email>
</sa:Sample>
Initial Value Enter the value of this variable.
Note used to an indirect reference or a method to populate this variable with a value from another model entity, such as the return from a service call.
When you specify an indirect reference such as "${Variables/foo}", the builder will use the indirect reference when the variable is first accessed and prior to any initialization.
Advanced
Instantiation Method Select or enter the name of the method you want to use to instantiate this variable. The choices you have in the select list will depend on the methods you've made public within the model.
State and Failover We can determine the failover behavior for variables by choosing a setting for the Persist Choice property in the Variable builder call editor. We can choose from the following values:
Read-Write - This setting prompts the model to save the current value for the Variable in the case of a failover event. This failover functionality does incur a small performance hit, so only use the Default setting when necessary.
Read-Write but not persisted for failover - This setting allows your Variable's value to change, but its value at the time of failover will not be preserved.
Read-only: shared across all users - This setting makes your variable behave like a constant. Its value will never change from the initial setting. As a result, some performance gains are realized because a copy of the Variable is not made during generation and the Variable is not processed during the failover event.
Request Scope - This setting will store the variable value in a request attribute rather than in a class (WebAppInstanceData). Doing this can improve performance for large variables that are set and read within a single request, and not needed across multiple requests.
Do not use Request Scope for items such as XML variables that are used in multiple requests. Doing so would clone and initialize the request copy of that variable for every use. Use Request Scope for infrequently used variables and variables that hold large objects or hierarchies of objects (such as XML). A typical use of request scope might be for a variable that contains data for a table that is displayed on only page of a multi-page application.
Initialize every fetch Enable this input if you want the Initialize via action to get called each time the variable is accessed. If the variable does not use an Initialize via action, enabling this input has no effect on the variable's initial value.
Regen sample data Enable this input if you want the initial value to be generated from the associated schema type.
Leave this input disabled if you want to retain the initial value of the variable during subsequent generations of the model.
Overwriting
Rename Existing This input is useful in cases where you want to change the behavior of code that was placed in the WebApp by a high-level builder or by an Imported Model.
For example, you might want to do this if you have a Domino View & Form builder in your model, and you want to use a different class for one of the LJO's that Builder adds to the WebApp. The Domino View and Form Builder does not provide an "LJO Class Name" input. But, we can place a new LJO Builder in the model and give it the same name as that assigned by the Domino View and From Builder, thus replacing the existing LJO and specifying new class.

Enable - When checked, this input will cause the Builder to replace an existing WebApp object with a new object. The Builder will locate the existing WebApp object (variable, LJO, etc.), rename it, and then create a replacement object.

This input is available on the following low-level Builders that create WebApp objects: Action List, Imported Page, Linked Java Object, Linked Model, Method, Method Call, Page, Variable and Schema.

Accessing Variable Values

We can access Variable values by using the Reference Chooser, available for most builder inputs or from Method builder calls and Linked Java Objects.

Using Methods

You access your model's Variables and their values by calling the webAppAccess.getVariables() method. These interfaces are documented in the WebSphere Portlet Factory API Javadoc.
See the Getting and Setting Variable Values topic for information on how to get and set variable values using methods.

Using Alternative APIs for DOM and JDOM Variables

If you specify an alternative Document Object Model ( DOM ) for a variable, we can use that DOM's API to access the elements of the XML contained by the variable. To use the APIs for these DOMs, make sure that the appropriate .jar file is in one of the Required Libraries for your project. Refer to the documentation for those APIs for specific information on how to interact with the XML for the variable.

Using Schemas to Provide Additional Data Types

We can declare a variable to be of a type other than the default types by adding a Schema builder to your model. When you open the Variable builder call editor, the types defined in the schema appear in the list of available types.
In addition, we can pre-populate the variable with the appropriate XML structure with sample text values for any appropriate elements by clicking the Create Sample Data button. Creating sample data is useful because it you don't have to build up the appropriate structure when you set the value of the variable, we can just set the text values of the individual elements in the structure.

Input Name	Description
Name	Enter a name for this builder call. The Designer displays this name in the Builder Call List.
Type	Enter the data type for the value that the variable will hold from one of the following choices: String Integer Double Float Long Boolean XMLData Object In addition to these standard data types, we can also declare variables to be of a type defined in a schema that you have added to the model with the Schema builder. For more information about assigning data types defined in a schema, see " Using Schemas to Provide Additional Data Types". Schemas that define many elements could cause an "Out of memory" error due to the fact that those elements need to be displayed as possible types by the Reference Chooser.
(Optional) Namespace	Enter the URL to the schema definition. If the schema referenced in the Schema builder call includes an xmlns declaration, that value is used to prepopulate this input.
(Optional) Namespace prefix	Enter a string that will be prepended to element names in the XML structure. For example, you could differentiate between two Address types by using a namespace prefix; perhaps ba for a billing address and sa for a shipping address. <sa:Sample xmlns:sa="http://bowstreet.com/2002/03/datamapper"> <sa:firstName>Sample firstName</sa:firstName> <sa:lastName>Sample lastName</sa:lastName> <sa:address1>Sample address1</sa:address1> <sa:address2>Sample address2</sa:address2> <sa:city>Sample city</sa:city> <sa:state>Sample state</sa:state> <sa:zip>Sample zip</sa:zip> <sa:phone>Sample phone</sa:phone> <sa:email>Sample email</sa:email> </sa:Sample>
Initial Value	Enter the value of this variable. Note used to an indirect reference or a method to populate this variable with a value from another model entity, such as the return from a service call. When you specify an indirect reference such as "${Variables/foo}", the builder will use the indirect reference when the variable is first accessed and prior to any initialization.
Advanced
Instantiation Method	Select or enter the name of the method you want to use to instantiate this variable. The choices you have in the select list will depend on the methods you've made public within the model.
State and Failover	We can determine the failover behavior for variables by choosing a setting for the Persist Choice property in the Variable builder call editor. We can choose from the following values: Read-Write - This setting prompts the model to save the current value for the Variable in the case of a failover event. This failover functionality does incur a small performance hit, so only use the Default setting when necessary. Read-Write but not persisted for failover - This setting allows your Variable's value to change, but its value at the time of failover will not be preserved. Read-only: shared across all users - This setting makes your variable behave like a constant. Its value will never change from the initial setting. As a result, some performance gains are realized because a copy of the Variable is not made during generation and the Variable is not processed during the failover event. Request Scope - This setting will store the variable value in a request attribute rather than in a class (WebAppInstanceData). Doing this can improve performance for large variables that are set and read within a single request, and not needed across multiple requests. Do not use Request Scope for items such as XML variables that are used in multiple requests. Doing so would clone and initialize the request copy of that variable for every use. Use Request Scope for infrequently used variables and variables that hold large objects or hierarchies of objects (such as XML). A typical use of request scope might be for a variable that contains data for a table that is displayed on only page of a multi-page application.
Initialize every fetch	Enable this input if you want the Initialize via action to get called each time the variable is accessed. If the variable does not use an Initialize via action, enabling this input has no effect on the variable's initial value.
Regen sample data	Enable this input if you want the initial value to be generated from the associated schema type. Leave this input disabled if you want to retain the initial value of the variable during subsequent generations of the model.
Overwriting
Rename Existing	This input is useful in cases where you want to change the behavior of code that was placed in the WebApp by a high-level builder or by an Imported Model. For example, you might want to do this if you have a Domino View & Form builder in your model, and you want to use a different class for one of the LJO's that Builder adds to the WebApp. The Domino View and Form Builder does not provide an "LJO Class Name" input. But, we can place a new LJO Builder in the model and give it the same name as that assigned by the Domino View and From Builder, thus replacing the existing LJO and specifying new class. Enable - When checked, this input will cause the Builder to replace an existing WebApp object with a new object. The Builder will locate the existing WebApp object (variable, LJO, etc.), rename it, and then create a replacement object. This input is available on the following low-level Builders that create WebApp objects: Action List, Imported Page, Linked Java Object, Linked Model, Method, Method Call, Page, Variable and Schema.