0
# JAXB2 Basics Runtime
1

2
Runtime support library for JAXB2 Basics plugins that provides strategic pattern implementations for equals, hashCode, toString, copying, and merging operations on JAXB-generated classes. This library enables reflection-free, high-performance implementations of common object operations while maintaining full compatibility with XML binding semantics.
3

4
## Package Information
5

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

18
## Core Imports
19

20
```java
21
import org.jvnet.jaxb2_commons.lang.*;
22
import org.jvnet.jaxb2_commons.locator.*;
23
```
24

25
For JAXB lifecycle callbacks:
26
```java
27
import org.jvnet.jaxb2_commons.xml.bind.*;
28
```
29

30
## Basic Usage
31

32
```java
33
import org.jvnet.jaxb2_commons.lang.*;
34
import org.jvnet.jaxb2_commons.locator.*;
35

36
// Example JAXB-generated class using strategic patterns
37
public class Person implements Equals2, HashCode2, ToString2, CopyTo2 {
38
    private String name;
39
    private int age;
40
    
41
    // Strategic equals implementation
42
    @Override
43
    public boolean equals(ObjectLocator thisLocator, ObjectLocator thatLocator, 
44
                         Object object, EqualsStrategy2 strategy) {
45
        if (!(object instanceof Person)) {
46
            return false;
47
        }
48
        Person that = (Person) object;
49
        return strategy.equals(LocatorUtils.property(thisLocator, "name", this.name),
50
                              LocatorUtils.property(thatLocator, "name", that.name),
51
                              this.name, that.name, true, true) &&
52
               strategy.equals(LocatorUtils.property(thisLocator, "age", this.age),
53
                              LocatorUtils.property(thatLocator, "age", that.age),
54
                              this.age, that.age, true, true);
55
    }
56
    
57
    // Strategic hashCode implementation  
58
    @Override
59
    public int hashCode(ObjectLocator locator, HashCodeStrategy2 strategy) {
60
        int hashCode = 1;
61
        hashCode = strategy.hashCode(LocatorUtils.property(locator, "name", this.name),
62
                                    hashCode, this.name, true);
63
        hashCode = strategy.hashCode(LocatorUtils.property(locator, "age", this.age),
64
                                    hashCode, this.age, true);
65
        return hashCode;
66
    }
67
    
68
    // Use default JAXB strategies
69
    @Override
70
    public boolean equals(Object object) {
71
        return Equals2.DefaultEqualsStrategy.INSTANCE.equals(
72
            new DefaultRootObjectLocator(this),
73
            new DefaultRootObjectLocator(object),
74
            object, JAXBEqualsStrategy.INSTANCE);
75
    }
76
    
77
    @Override
78
    public int hashCode() {
79
        return HashCode2.DefaultHashCodeStrategy.INSTANCE.hashCode(
80
            new DefaultRootObjectLocator(this), JAXBHashCodeStrategy.INSTANCE);
81
    }
82
}
83
```
84

85
## Architecture
86

87
The library is built around the **Strategy Pattern**, providing pluggable implementations for common object operations:
88

89
- **Behavioral Interfaces**: Core interfaces (Equals2, HashCode2, ToString2, CopyTo2, MergeFrom2) that JAXB-generated classes implement
90
- **Strategy Interfaces**: Define how operations are performed (EqualsStrategy2, HashCodeStrategy2, etc.)
91
- **Default Implementations**: Provide standard behavior for all Java types
92
- **JAXB Implementations**: Provide XML-aware behavior for JAXB types (JAXBElement, Collections)
93
- **Object Locators**: Track object navigation paths for debugging and error reporting
94
- **Model Abstraction**: Comprehensive abstraction layer over JAXB model metadata
95

96
This architecture enables consistent, high-performance operations across complex JAXB object hierarchies while maintaining full type safety and providing detailed error reporting capabilities.
97

98
## Capabilities
99

100
### Strategic Pattern Implementations
101

102
Core behavioral interfaces and strategy implementations for equals, hashCode, toString, copy, and merge operations. These form the foundation that JAXB2 Basics plugins use to generate efficient, reflection-free method implementations.
103

104
```java { .api }
105
// Main behavioral interfaces (current API with value set tracking)
106
interface Equals2 {
107
    boolean equals(ObjectLocator thisLocator, ObjectLocator thatLocator, 
108
                  Object object, EqualsStrategy2 strategy);
109
}
110

111
interface HashCode2 {
112
    int hashCode(ObjectLocator locator, HashCodeStrategy2 strategy);
113
}
114

115
interface ToString2 {
116
    StringBuilder append(ObjectLocator locator, StringBuilder buffer, 
117
                        ToStringStrategy2 strategy);
118
    StringBuilder appendFields(ObjectLocator locator, StringBuilder buffer, 
119
                              ToStringStrategy2 strategy);
120
}
121

122
interface CopyTo2 {
123
    Object createNewInstance();
124
    Object copyTo(Object target);
125
    Object copyTo(ObjectLocator locator, Object target, CopyStrategy2 strategy);
126
}
127

128
interface MergeFrom2 {
129
    Object createNewInstance();
130
    void mergeFrom(Object left, Object right);
131
    void mergeFrom(ObjectLocator leftLocator, ObjectLocator rightLocator, 
132
                  Object left, Object right, MergeStrategy2 strategy);
133
}
134
```
135

136
[Strategic Patterns](./strategic-patterns.md)
137

138
### Object Location Tracking  
139

140
Object locator system for tracking navigation paths through object hierarchies. Essential for debugging, error reporting, and providing context during strategic operations.
141

142
```java { .api }
143
interface ObjectLocator extends ValidationEventLocator, Reportable {
144
    ObjectLocator getParentLocator();
145
    ObjectLocator[] getPath();
146
    String getPathAsString();
147
    PropertyObjectLocator property(String propertyName, Object propertyValue);
148
    ItemObjectLocator item(int itemIndex, Object itemValue);
149
}
150

151
class DefaultRootObjectLocator implements RootObjectLocator {
152
    public DefaultRootObjectLocator(Object rootObject);
153
}
154
```
155

156
[Object Locators](./object-locators.md)
157

158
### JAXB Lifecycle Integration
159

160
Callback interfaces for integrating with JAXB marshalling and unmarshalling lifecycle events, enabling custom processing during XML binding operations.
161

162
```java { .api }
163
interface BeforeMarshallCallback {
164
    void beforeMarshall(Marshaller marshaller);
165
}
166

167
interface AfterMarshallCallback {
168
    void afterMarshall(Marshaller marshaller);
169
}
170

171
interface BeforeUnmarshallCallback {
172
    void beforeUnmarshal(Unmarshaller unmarshaller, Object parent);
173
}
174

175
interface AfterUnmarshallCallback {
176
    void afterUnmarshal(Unmarshaller unmarshaller, Object parent);
177
}
178
```
179

180
[JAXB Lifecycle](./jaxb-lifecycle.md)
181

182
### JAXB Model Abstraction
183

184
Comprehensive abstraction layer over JAXB model information providing vendor-neutral access to type metadata, property information, and schema details through visitor pattern support.
185

186
```java { .api }
187
interface MModelInfo<T, C extends T> extends MCustomizable {
188
    Collection<MBuiltinLeafInfo<T, C>> getBuiltinLeafInfos();
189
    Collection<MClassInfo<T, C>> getClassInfos();
190
    MClassInfo<T, C> getClassInfo(String name);
191
    Collection<MEnumLeafInfo<T, C>> getEnumLeafInfos();
192
    Collection<MTypeInfo<T, C>> getTypeInfos();
193
    MTypeInfo<T, C> getTypeInfo(QName typeNam);
194
    Collection<MElementInfo<T, C>> getElementInfos();
195
    MElementInfo<T, C> getGlobalElementInfo(QName elementName);
196
}
197

198
interface MClassInfo<T, C> extends MClassTypeInfo<T, C> {
199
    List<MPropertyInfo<T, C>> getProperties();
200
    MPropertyInfo<T, C> getProperty(String publicName);
201
    QName getElementName();
202
}
203
```
204

205
[JAXB Model Abstraction](./jaxb-model.md)
206

207
### Utility Classes
208

209
Essential utility classes for string manipulation, class name handling, validation, JAXB context management, and XML Schema constants.
210

211
```java { .api }
212
class StringUtils {
213
    static boolean isEmpty(String str);
214
    static String[] split(String str, char separatorChar);
215
    static String join(Iterator iterator, String separator);
216
}
217

218
class ClassUtils {
219
    static String getShortClassName(Class cls);
220
    static String getShortClassName(String className);
221
}
222

223
class ContextUtils {
224
    static String getContextPath(Class<?>... classes);
225
    static String toString(JAXBContext context, Object object);
226
}
227
```
228

229
[Utilities](./utilities.md)