0
# XML Configuration Processing
1

2
Core functionality for loading XML configuration files and applying them to Java objects through reflection-based dependency injection. The XmlConfiguration class serves as the main entry point for the IoC container functionality.
3

4
## Capabilities
5

6
### XmlConfiguration Class
7

8
The primary class for processing XML configuration files and applying them to Java objects.
9

10
```java { .api }
11
/**
12
 * Configures objects from XML files conforming to configure.dtd DTD
13
 */
14
class XmlConfiguration {
15
    /**
16
     * Create configuration from a resource
17
     * @param resource XML configuration resource
18
     */
19
    XmlConfiguration(Resource resource);
20
    
21
    /**
22
     * Create configuration with shared state
23
     * @param resource XML configuration resource
24
     * @param idMap shared map of object IDs between configurations
25
     * @param properties shared properties for parameterization
26
     */
27
    XmlConfiguration(Resource resource, Map<String, Object> idMap, Map<String, String> properties);
28
}
29
```
30

31
### Configuration Execution
32

33
Apply XML configuration to create or configure objects.
34

35
```java { .api }
36
/**
37
 * Apply XML configuration script, creating new objects as needed
38
 * @return the configured object
39
 * @throws Exception if configuration fails
40
 */
41
Object configure() throws Exception;
42

43
/**
44
 * Apply XML configuration to an existing object
45
 * @param obj the object to configure
46
 * @return the configured object
47
 * @throws Exception if configuration fails
48
 */
49
Object configure(Object obj) throws Exception;
50

51
/**
52
 * Hook for initializing object defaults (override point)
53
 * @param object the object to initialize
54
 */
55
void initializeDefaults(Object object);
56
```
57

58
### State Management
59

60
Manage shared state between multiple configuration instances.
61

62
```java { .api }
63
/**
64
 * Get modifiable map of ID strings to objects for sharing between configurations
65
 * @return map of object IDs
66
 */
67
Map<String, Object> getIdMap();
68

69
/**
70
 * Get modifiable map of properties for parameterizing configuration
71
 * @return properties map
72
 */
73
Map<String, String> getProperties();
74

75
/**
76
 * Set standard Jetty IDs and properties
77
 * @param server the server object
78
 * @param webapp path to webapp
79
 */
80
void setJettyStandardIdsAndProperties(Object server, Path webapp);
81
```
82

83
### Utility Methods
84

85
Helper methods for configuration processing.
86

87
```java { .api }
88
/**
89
 * Get an XML parser instance
90
 * @return XmlParser instance
91
 */
92
XmlParser getXmlParser();
93

94
/**
95
 * Normalize URI by removing trailing slash
96
 * @param uri the URI to normalize
97
 * @return normalized URI
98
 */
99
static String normalizeURI(String uri);
100

101
/**
102
 * Resolve path against directory
103
 * @param dir base directory
104
 * @param destPath destination path
105
 * @return resolved path
106
 */
107
static String resolvePath(String dir, String destPath);
108
```
109

110
### Main Application Support
111

112
Run XML configurations as standalone applications.
113

114
```java { .api }
115
/**
116
 * Run XML configurations as main application with property and XML file support
117
 * @param args command line arguments
118
 */
119
static void main(String... args);
120
```
121

122
## Usage Examples
123

124
### Basic Configuration
125

126
```java
127
import org.eclipse.jetty.xml.XmlConfiguration;
128
import org.eclipse.jetty.util.resource.Resource;
129

130
// Load XML configuration
131
Resource configXml = Resource.newResource("server-config.xml");
132
XmlConfiguration config = new XmlConfiguration(configXml);
133

134
// Apply configuration to create objects
135
Object server = config.configure();
136
```
137

138
### Configure Existing Object
139

140
```java
141
// Configure an existing object
142
MyServer server = new MyServer();
143
XmlConfiguration config = new XmlConfiguration(Resource.newResource("server.xml"));
144
config.configure(server);
145
```
146

147
### Multi-File Configuration with Shared State
148

149
```java
150
// First configuration
151
XmlConfiguration config1 = new XmlConfiguration(Resource.newResource("base-config.xml"));
152
Object baseServer = config1.configure();
153

154
// Second configuration sharing IDs and properties
155
XmlConfiguration config2 = new XmlConfiguration(
156
    Resource.newResource("additional-config.xml"),
157
    config1.getIdMap(),      // Share object registry
158
    config1.getProperties()  // Share properties
159
);
160

161
// Objects in config2 can reference IDs from config1
162
Object enhancedServer = config2.configure();
163
```
164

165
### Property Parameterization
166

167
```java
168
XmlConfiguration config = new XmlConfiguration(Resource.newResource("parameterized.xml"));
169

170
// Set properties for substitution in XML
171
config.getProperties().put("server.port", "8080");
172
config.getProperties().put("server.host", "localhost");
173

174
Object server = config.configure();
175
```
176

177
### Command Line Usage
178

179
```bash
180
# Run XML configuration as main application
181
java -cp jetty-xml.jar org.eclipse.jetty.xml.XmlConfiguration server.xml
182

183
# With properties
184
java -Dserver.port=8080 -cp jetty-xml.jar org.eclipse.jetty.xml.XmlConfiguration server.xml
185

186
# Multiple files
187
java -cp jetty-xml.jar org.eclipse.jetty.xml.XmlConfiguration base.xml additional.xml
188
```
189

190
## XML Configuration Format
191

192
The library uses a DTD-based XML format for configuration:
193

194
```xml
195
<?xml version="1.0" encoding="UTF-8"?>
196
<!DOCTYPE Configure PUBLIC "-//Jetty//Configure//EN" 
197
    "https://www.eclipse.org/jetty/configure_12_0.dtd">
198

199
<Configure class="com.example.Server">
200
  <!-- Set properties -->
201
  <Set name="port"><Property name="server.port" default="8080"/></Set>
202
  <Set name="host"><Property name="server.host" default="localhost"/></Set>
203
  
204
  <!-- Create and configure nested objects -->
205
  <Call name="addConnector">
206
    <Arg>
207
      <New class="com.example.Connector">
208
        <Set name="port"><Ref refid="server.port"/></Set>
209
      </New>
210
    </Arg>
211
  </Call>
212
  
213
  <!-- Reference objects by ID -->
214
  <New id="handler" class="com.example.Handler"/>
215
  <Call name="setHandler">
216
    <Arg><Ref refid="handler"/></Arg>
217
  </Call>
218
</Configure>
219
```
220

221
## Configuration Elements
222

223
- **Configure**: Root element specifying target class
224
- **Set**: Call setter method
225
- **Get**: Call getter method  
226
- **Call**: Call arbitrary method
227
- **New**: Create new object instance
228
- **Ref**: Reference object by ID
229
- **Property**: Property value substitution
230
- **Arg**: Method/constructor argument
231
- **Array**: Create array values
232

233
## Error Handling
234

235
Configuration errors are wrapped in XmlConfigurationException:
236

237
```java
238
try {
239
    Object result = config.configure();
240
} catch (XmlConfigurationException e) {
241
    // Handle configuration-specific errors
242
    Throwable cause = e.getCause();
243
    String message = e.getMessage();
244
}
245
```
246

247
## Constants
248

249
```java { .api }
250
/**
251
 * Comparator for ranking methods and constructors by parameter compatibility
252
 */
253
static final Comparator<Executable> EXECUTABLE_COMPARATOR;
254
```