0
# Jetty XML Configuration
1

2
XML-based configuration utilities for Eclipse Jetty providing an Inversion of Control (IoC) mechanism for component configuration. The library enables declarative configuration of Jetty components and general Java objects through XML files, supporting property substitution, bean ID management, and extensible configuration processing.
3

4
## Package Information
5

6
- **Package Name**: org.eclipse.jetty:jetty-xml
7
- **Package Type**: maven
8
- **Language**: Java
9
- **Installation**: Add dependency to Maven pom.xml:
10
  ```xml
11
  <dependency>
12
    <groupId>org.eclipse.jetty</groupId>
13
    <artifactId>jetty-xml</artifactId>
14
    <version>12.0.21</version>
15
  </dependency>
16
  ```
17

18
## Core Imports
19

20
```java
21
import org.eclipse.jetty.xml.XmlConfiguration;
22
import org.eclipse.jetty.xml.XmlParser;
23
import org.eclipse.jetty.xml.XmlAppendable;
24
```
25

26
## Basic Usage
27

28
```java
29
import org.eclipse.jetty.xml.XmlConfiguration;
30
import org.eclipse.jetty.util.resource.Resource;
31

32
// Load and apply XML configuration
33
Resource xmlResource = Resource.newResource("jetty-config.xml");
34
XmlConfiguration config = new XmlConfiguration(xmlResource);
35

36
// Configure a new object from XML
37
Object configuredObject = config.configure();
38

39
// Or configure an existing object
40
MyServer server = new MyServer();
41
config.configure(server);
42

43
// Share configuration state between multiple XML files
44
XmlConfiguration config2 = new XmlConfiguration(
45
    Resource.newResource("jetty-config2.xml"),
46
    config.getIdMap(),      // Share object IDs
47
    config.getProperties()  // Share properties
48
);
49
```
50

51
## Architecture
52

53
The Jetty XML configuration system is built around several key components:
54

55
- **XmlConfiguration**: Core engine that processes XML files and applies configuration through reflection
56
- **XmlParser**: SAX-based XML parser with validation and entity resolution capabilities
57
- **ConfigurationProcessor**: Extensible processing system allowing custom configuration formats
58
- **Property System**: Parameterized configuration with property substitution
59
- **ID Management**: Object registry for cross-referencing between configuration files
60
- **Environment Support**: Isolated runtime environments with custom classpaths
61

62
## Capabilities
63

64
### XML Configuration Processing
65

66
Core functionality for loading XML configuration files and applying them to Java objects through reflection-based dependency injection.
67

68
```java { .api }
69
class XmlConfiguration {
70
    XmlConfiguration(Resource resource);
71
    XmlConfiguration(Resource resource, Map<String, Object> idMap, Map<String, String> properties);
72
    
73
    Object configure() throws Exception;
74
    Object configure(Object obj) throws Exception;
75
    
76
    Map<String, Object> getIdMap();
77
    Map<String, String> getProperties();
78
}
79
```
80

81
[XML Configuration](./xml-configuration.md)
82

83
### XML Parsing and Document Processing
84

85
Advanced XML parsing capabilities with validation, entity resolution, and DOM-like tree processing.
86

87
```java { .api }
88
class XmlParser {
89
    XmlParser();
90
    XmlParser(boolean validating);
91
    
92
    Node parse(String url) throws IOException, SAXException;
93
    Node parse(File file) throws IOException, SAXException;
94
    Node parse(InputStream in) throws IOException, SAXException;
95
    
96
    void setValidating(boolean validating);
97
    void addCatalog(URI catalogXml);
98
}
99
```
100

101
[XML Parser](./xml-parser.md)
102

103
### XML Generation and Output
104

105
Utilities for programmatically generating well-formed XML with proper indentation and encoding.
106

107
```java { .api }
108
class XmlAppendable {
109
    XmlAppendable(OutputStream out);
110
    
111
    XmlAppendable openTag(String tag);
112
    XmlAppendable openTag(String tag, Map<String, String> attributes);
113
    XmlAppendable closeTag();
114
    XmlAppendable tag(String tag, String content);
115
    XmlAppendable content(String s);
116
}
117
```
118

119
[XML Generation](./xml-generation.md)
120

121
### Configuration Extension and Customization
122

123
Extensible configuration processing system supporting custom configuration formats and processors.
124

125
```java { .api }
126
interface ConfigurationProcessor {
127
    void init(Resource resource, XmlParser.Node root, XmlConfiguration configuration);
128
    Object configure(Object obj) throws Exception;
129
    Object configure() throws Exception;
130
}
131

132
interface ConfigurationProcessorFactory {
133
    ConfigurationProcessor getConfigurationProcessor(String dtd, String tag);
134
}
135
```
136

137
[Configuration Extension](./configuration-extension.md)
138

139
## Types
140

141
```java { .api }
142
class XmlConfigurationException extends IllegalStateException {
143
    XmlConfigurationException(String s);
144
    XmlConfigurationException(String message, Throwable cause);
145
}
146

147
class XmlParser.Node {
148
    String getTag();
149
    String getAttribute(String name);
150
    Node get(String tag);
151
    Iterator<Node> iterator(String tag);
152
}
153

154
class XmlParser.Attribute {
155
    String getName();
156
    String getValue();
157
}
158

159
class BaseClassCatalog implements Catalog, EntityResolver {
160
    static BaseClassCatalog load(URI uriToCatalogXml, Class<?> baseClass);
161
    String matchPublic(String publicId);
162
    String matchSystem(String systemId);
163
}
164

165
class EnvironmentBuilder {
166
    EnvironmentBuilder(String name);
167
    void addClassPath(String... classPaths);
168
    void addModulePath(String modulePath);
169
    Environment build();
170
}
171
```