x OBSOLETE (v1.x) Stub Configuration, XML based
This page is valid for Wilma versions <=1.6.x.
When Wilma is upgraded to version 2.x, a major change has happened in its configuration. The XML based configuration has been replaced with JSON based configuration.
Information about the new configuration approach is available here.
The most important part of the Stub part is its configuration. When the approach is designed some key points were considered:
- It must be usable for any kind of SW development project that needs a stub solution. Therefore it must be independent from the projects.
- It must be flexible enough to be extended by testers/developers if project specific things should be added.
- It must be easy to implement and use
- It must be easy to change the configuration on the fly (during run-time), even for temporary configs.
An XML based approach was selected, see details about the XML content below.
Main elements: wilma-stub, dialog-descriptor and template-descriptor
<wilma-stub>
1..N* <dialog-descriptor name="UNIQUE_NAME_OF_THE_DIALOG_DESCRIPTOR" usage="always"|"timeout"|"hitcount"|"disabled" validityvalue="N" comment="whatevertext">
1: <condition-descriptor .... />
1: <response-descriptor ..../>
</dialog-descriptor>
1..N* <template-descriptor name="UNIQUE_NAME_OF_THE_TEMPLATE_DESCRIPTOR" >
0..N*: <template-formatter-set />
1..N*: <template ... />
</template-descriptor>
0..N* <condition-templates name="UNIQUE_NAME_OF_THE_CONDITION_TEMPLATES">
1..N*: <condition-set ..../>
</condition-templates>
</wilma-stub>
Element: dialog-descriptor The stub configuration contains several dialog-descriptors that describes a request-response pair - with what response the stub should answer in case of a specific request.
Its name should be meaningful and unique.
usage is optional, default value: always,
- always means this dialog descriptor is valid when Wilma is running.
- timeout means that when this node appears, after a timeout (specified in minutes in validityvalue), the node will be disabled
- hitcount means that after this descriptor is applied N times (defined in validityvalue), the node will be disabled
- disabled means that the dialog descriptor is not in use
comment attribute is optional, may be used to describe the purpose of the dialog descriptor (like: "This req-resp pair is to test bad response from X service, when xxx attribute is missing, however should not.")
On-the-fly behavior: nodes can be added / removed on-the-fly by using Wilma admin pages. When a node become disabled and that node was not originally in the starting Wilma-stub, the node itself should be deleted as well from the active structure.
Element: condition-descriptor
This element describes a complex condition which should be evaluated by the switch engine (= part of Wilma that decides between proriing the request or generating s stub response).
method: ResponseDescriptor evaluateCondition(DialogDescriptor, RequestMessage), -> evaluates the ConditionDescriptor part and returns with the ResponseDescriptor class is condition matched, or NULL in case condition failed.
When has value -> Stub shall be activated with the ResponseDescriptor info.
When has no value (NULL) -> goes to next DialogDescriptor, or if no such left -> proxy mode
<condition-descriptor>
1: <boolean-condition>
1..N*: <condition ... /> | <boolean-condition .../> | <condition-set-invoker .../>
</boolean-condition>
|
1: <condition .../>
|
1: <condition-set-invoker name="nameofthespecificconditionset" />
</condition-descriptor>
where
<boolean-condition/> can be: <and>[conditions]</and>, <or>[conditions]</or>, <not>[single condition]</not>: logical OR or AND between its sub-element values or negate the result. Sub-elements can be boolean-condition(s) and/or conditions and/or condition-set-invokers.
<condition-set-invoker name="nameofthespecificconditionset"/> just evaluates the given condition-set.
Pls note, that by referring to itself, an endless loop can be configured -> this is checked and forbidden by Wilma
condition descriptor contains either 1 boolean-condition, or 1 condition, or 1 condition-set-invoker
Element: condition This element describes a single condition that should be evaluated, its result is a boolean value.
<condition
class=xxxCheckerClass
negate=false|true - optional, negates the final result of the condition, default=false
>
0..N: <param name="xxxx" value="yyy" />
</condition>
class is the type of the check. See details at Built-in condition checker classes.
If the class is not a built-in one, then the class should be loaded dynamically and its checker method should be called.
Used interface: boolean conditionEvaluator(RequestMessage, negate, param[])
See Built-in condition checker classes page to get further information about built-in condition checkers usage.
Note: used external classes are loaded at evaluation of the configuration, not later.
Method defines how the condition is checked. Checking the message type, checking element existence, its value, etc etc (or the evaluator class itself).
param element is optional and should be as many as expected by the class/method pair. The value of "Name" and "Value" attributes should be Strings, no further restriction is allowed.
Element: response-descriptor
This element describes what answer should be sent back, and in case a template is used, what method should be used to make it up-to-date.
<response-descriptor
delay=N - optional, default value is 0, delay of the response in seconds, 0 means no delay
code=N - optional, response code, default value is 200 (here E500 and others can be specified)
mimetype=text/plain|text/html|text/xml|application/xml|application/soap+xml|application/json - describes the response content type
template=templeName - name of the template to be used for the answer
>
0..N*: <template-formatter class=templateFormatterClassName>
0..N: <param name="xxxx" value="yyy" />
</template-formatter>
0..N*: <template-formatter-set-invoker name=nameofthespecificformatterset />
/>
template-formatters and template-formatter-set-invokers are called in order, from top to bottom, class defines the method, can be external too, by calling TemplateResource formatTemplate(RequestMessage, TemplateResource, Param[]) method
template-formatters and template-formatter-set-invokers can be mixed, as necessary
See Template Formatters page to get further information about template formatters usage.
param is as many as necessary for the class to work on resource. The value of "Name" and "Value" attributes should be Strings, no further restriction is allowed.
template-formatter-set-invokers just applies the specific template-formatter-set on the resource.
Pls note, that by referring to itself, an endless loop can be configured -> this is checked and forbidden by Wilma.
Element: template-descriptor
The template-descriptor part contains many template definitions, and methods how the actual template elements should be filled. The same physical response template can be used by several template-descriptors, as the same template - by using different fill methods - can be used for different purposes.
Element: template
This element describes a template file and how it should be handled when it is used as response.
<template
name=UNIQUE_NAME_FOR_THIS_TEMPLATE
type=text|xmlfile|htmlfile|textfile|external
resource=xxx />
type is the type of the resource. in case of text, it is embedded (resource contains the value), other case (*file) name of the file
in case of external, the resource should be a class name, that class should be loaded and its String loadTemplateResource(name) method (interface) will be called in order to generate the template.
Resource is always a String (meaning depends on the type).
Element: template-formatter-set
This element is used to collect a set of template formatters, in order to use them later on templates.
<template-formatter-set name=UNIQUENAMEOFTHEFORMATTERSET>
0..N*: <template-formatter class=templateFormatterClassName>
0..N: <param name="xxxx" value="yyy" />
</template-formatter>
0..N*: <template-formatter-set-invoker name=nameofthespecificformatterset>
</template-formatter-set>
See Element: response-descriptor for details on sub-elements
Element condition-templates
This element contains reusable condition sets those can be called in the condition-descriptor. Contains 1..N condition-sets.
Condition templates have unique names.
Element condition-set This element contains reusable condition sets those can be called in the condition-descriptor.
<condition-set name="UNIQUE_NAME_OF_THE CONDITION_SET">
1: <boolean-condition>
2..N*: <condition ... /> | <boolean-condition .../> | <condition-set-invoker .../>
</boolean-condition>
|
1: <condition .../>
|
1: <condition-set-invoker name=nameofthespecificconditionset />
</condition-set>
Note: The ONLY diff between condition-descriptor and condition-set is that condition-set has a unique name.
Validation: the configuration xml should be validated, not just formally, but logically too (like if a dialog-descriptor refers to a template, then there should be a template descriptor for it)
In case of validation error:
- at Wilma startup check: Wilma writes meaningful error message to console and exits
- at run-time: change requests are refused (with meaningful error message), and the original - validated - configuration remains in use
See Example Stub configuration page to get some real world usage possibilities.
Among the main elements of configuration xml described here, further elements may exist in the xml file, like