Sun Java System Application Server Standard and Enterprise Edition 7 2004Q2 Update 3 Administration Guide |
Appendix E
HTTP Load Balancer Configuration FileThe loadbalancer.xml file contains the configuration information for load balancing Sun Java System Application Server 7 Enterprise Edition instances. This file is part of the load balancer plug-in for the front-end web server. Although located in the web server, it is described in this manual because of its importance and relevance to the Sun Java System Application Server.
The encoding of the loadbalancer.xml file is UTF-8 to maintain compatibility with regular UNIX text editors. A schema file, sun-loadbalancer_1_1.dtd, determines the format and content of the loadbalancer.xml file.
This chapter describes loadbalancer.xml and sun-loadbalancer_1_1.dtd files in these sections:
sun-loadbalancer_1_1.dtd File
The sun-loadbalancer_1_1.dtd file defines the structure of the loadbalancer.xml file, including the elements it can contain and the subelements and attributes these elements can have.
Note
Do not edit the sun-loadbalancer_1_1.dtd file; its contents change only with new versions of Sun Java System Application Server Enterprise Edition.
For general information about DTD files and XML, see the XML specification at:
Each element defined in a DTD file (which may be present in the corresponding XML file) can contain the following:
Subelements
Elements can contain subelements. For example, the following file fragment defines the cluster element.
<!ELEMENT cluster (instance*, web-module*, health-checker?)>
The ELEMENT tag specifies that a cluster element can contain instance, web-module, and health-checker elements in that order.
The following table shows how optional suffix characters of subelements determine the requirement rules, or number of allowed occurrences, for the subelements. The left column lists the subelement ending character, and the right column lists the corresponding requirement rule.
If an element cannot contain other elements, you see EMPTY or (#PCDATA) instead of a list of element names in parentheses.
Data
Some elements contain character data instead of subelements. These elements have definitions of the following format:
<!ELEMENT element-name (#PCDATA)>
For example:
<!ELEMENT description (#PCDATA)>
In the loadbalancer.xml file, white space is treated as part of the data in a data element. Therefore, there should be no extra white space before or after the data delimited by a data element. For example:
<description>response timeout property</description>
Attributes
Elements that have ATTLIST tags contain attributes (name-value pairs). For example:
<!ATTLIST instance name CDATA #REQUIRED
enabled %boolean; "true"
disable-timeout-in-minutes CDATA "31"
listeners CDATA #REQUIRED>An instance element can contain name, enabled, disable-timeout-in-minutes, and listeners attributes.
The #REQUIRED label means that a value must be supplied. The #IMPLIED label means that the attribute is optional, and that Sun Java System Application Server generates a default value. Wherever possible, explicit defaults for optional attributes (such as "true") are listed.
Attribute declarations specify the type of the attribute. For example, CDATA means character data, and %boolean is a predefined enumeration.
Elements in the loadbalancer.xml File
This section describes the XML elements in the loadbalancer.xml file.
Note
Subelements must be defined in the order in which they are listed under each Subelements heading unless otherwise noted.
loadbalancer
Defines a load balancer. This is the root element; there can only be one loadbalancer element in a loadbalancer.xml file.
Subelements
The following table describes subelements for the loadbalancer element. The left column lists the subelement name, the middle column indicates the requirement rule, and the right column describes what the element does.
Table E-2 loadbalancer subelements
Element
Required
Description
zero or more
Defines a cluster of server instances.
zero or more
Specifies a load balancer property.
Attributes
none
property
Specifies a load balancer property.
Subelements
The following table describes subelements for the property element. The left column lists the subelement name, the middle column indicates the requirement rule, and the right column describes what the element does.
Table E-3 property subelements
Element
Required
Description
zero or one
Contains a text description of this element.
Attributes
The following table describes attributes for the property element. The left column lists the attribute name, the middle column indicates the default value, and the right column describes what the attribute does.
Table E-4 property attributes
Attribute
Default
Description
name
none
Specifies the name of the property.
value
none
Specifies the value of the property.
Properties
The following table describes load balancer properties. The left column lists the property name, the middle column indicates the default value if the property is not present, and the right column describes what the property does.
description
Contains a text description of the parent element.
Subelements
none
Attributes
none
cluster
Defines a cluster of server instances.
Subelements
The following table describes subelements for the cluster element. The left column lists the subelement name, the middle column indicates the requirement rule, and the right column describes what the element does.
Table E-6 cluster subelements
Element
Required
Description
zero or more
Defines a server instance.
zero or more
Defines a web module.
zero or one
Configures the cluster’s health checker.
Attributes
The following table describes attributes for the cluster element. The left column lists the attribute name, the middle column indicates the default value, and the right column describes what the attribute does.
Table E-7 cluster attributes
Attribute
Default
Description
name
none
Specifies the name of the cluster. Within a load balancer, cluster names must be unique.
instance
Defines a server instance.
Subelements
none
Attributes
The following table describes attributes for the instance element. The left column lists the attribute name, the middle column indicates the default value, and the right column describes what the attribute does.
web-module
Defines a web module.
Subelements
The following table describes subelements for the web-module element. The left column lists the subelement name, the middle column indicates the requirement rule, and the right column describes what the element does.
Table E-9 web-module subelements
Subelement
Required
Description
idempotent-url-pattern
zero or more
Defines the idempotent URLs to be retried.
Attributes
The following table describes attributes for the web-module element. The left column lists the attribute name, the middle column indicates the default value, and the right column describes what the attribute does.
idempotent-url-pattern
Defines the URL pattern of requests that the load balancer can retry in case of a failure, on healthy server instances.
Attributes
The following table describes attributes for the idempotent-url-pattern subelement. The left column lists the attribute name, the middle column indicates the default value, and the right column describes what the attribute does.
health-checker
Configures the cluster’s health checker.
Subelements
none
Attributes
The following table describes attributes for the health-checker element. The left column lists the attribute name, the middle column indicates the default value, and the right column describes what the attribute does.