ParameterBuilder Interface

The ParameterBuilder interface and the classes derived from it contain methods to create a serialized string of information that is used primarily for constructing URLs and hidden inputs for forms. The ParameterBuilder interface defines the interface between a WebEvent and the format in which information about the event will be persisted, and it specifies the minimum information that should be persisted. (The individual implementations of ParameterBuilder choose how that information will be persisted.) The ParameterBuilder interface is used in all MicroStrategy Web transforms.

The ParameterBuilder class is distinct from the WebEvent and WebComponent classes, which do not need to know anything about serialization formats or how name/value pairs are converted into a URL or hidden input.

The sample URL below illustrates the discrete elements of information that can be constructed using ParameterBuilder methods:

http://localhost/myWebSite/mstrWeb_variation?paramname1=paramvalue1&paramname2=paramvalue2

targetPrefix	Sets a prefix to the targetBase. It is normally used to add an absolute path to the value of targetBase. For example, the absolute path to an element is required when exporting to Excel.
targetBase	Specifies the name of the servlet or resource that should be accessed. For example, “mstrWeb” would be the target for most of the links in the application. You can also use the name of an image or other resource if the link needs to point to some other place.
targetSuffix	Sets a suffix to the targetBase. Although it is not used by the application, it is added for consistency purposes. It allows you to add more information at the end of the target base.
parameters	When building forms or URLs, parameters define a name/value pair that can be sent on the request. Each name/value pair defines a different parameter and provide the means by which the application preserves events, object ids, and the state of beans in URLs and forms.

Any or all of these elements can be serialized into several different forms, but the two most common forms are as a URL or as a set of hidden inputs in a form.

The terms URL and URI are used interchangeably. Both are short strings that identify resources in the web— documents, images, downloadable files, services, electronic mailboxes, and other resources. Technically, the term URI stands for Uniform Resource Identifier, while the term URL stands for Uniform Resource Locator.

The ContainerServices interface acts as a factory for ParameterBuilder classes. It has two important methods that each return an instance of an object that implements the ParameterBuilder interface. One object instance is used to construct URLs and the other is used to build hidden inputs. Another method provides namespace support in a portal environment.

The newURIParameterBuilder method creates a new instance of an object that can be used to build dynamic URIs.
The newHiddenInputParameterBuilder method creates a new instance of an object that can be used to build a collection of hidden inputs.
The newNamespaceEncoder method is used in portal environments to create a new instance of an object that can be used to namespace URIs and form fields.

The ParameterBuilder class has two abstract base classes, which are used as a basis for implementations.

The AbstractParameterBuilder class is responsible for collecting all of the target-related components (targetPrefix, targetBase, and TargetSuffix) and parameter name/value pairs in protected data members.
The AbstractConfigurableParameterBuilder class is responsible for ensuring that the parameters specified in an external properties file are persisted from the request to every form and URL built by the Web application.

The ParameterBuilder class has two major implementation classes.

The DefaultURIBuilderImpl class is responsible for constructing a string that is used to create values that are persisted in the URL.

The DefaultHiddenInputBuilderImpl class is responsible for constructing a string that is used to create hidden inputs that are passed in forms.

The primary responsibility of both of these implementation classes is to construct a string from a collection of parameters, with a secondary responsibility to include target components in the string. The string they construct is used to generate either a URL or a hidden input field for a form. Both implementation classes can determine whether a parameter is considered “empty” and can parse a fragment into a set of parameters. (For the normal URI builder, the parameter is considered empty if there is no target base and no parameters.)

Supplying fragments that must be parsed is not a recommended practice, but it is required in situations where the application cannot discern what the original name/value pairs were. An example of such a case would be a user-supplied extraUrl and extraInput parameter managed by EventManager. These values originate from the Style Catalog Configuration file and do not exist as disparate name/value pairs.

Two other classes are used primarily or solely in portal environments:

The NamespaceEncoder class is responsible for encoding static URIs and form fields that need to be namespaced. The strings are properly namespaced using portal-specific APIs for specific third-party portal environments. For example, in a WebSphere portal environment, the standard DefaultHiddenInputBuilderImpl class is used, but the WebSphere-specific WPSNamespaceEncoderImpl is used instead of the EmptyNamespaceEncoderImpl. When Web Universal is deployed in a non-portal environment, there is no namespace encoding.

The WPSURIBuilderImpl class is responsible for building a dynamic URI to be used in a WebSphere portal environment.