or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

index.mdjaxb-lifecycle.mdjaxb-model.mdobject-locators.mdstrategic-patterns.mdutilities.md
tile.json

utilities.mddocs/

Utility Classes

Essential utility classes for string manipulation, class name handling, validation, JAXB context management, and XML Schema constants. These utilities provide common functionality used throughout the JAXB2 Basics runtime library.

Capabilities

String Manipulation

final class StringUtils {
    // String constants
    static final String LINE_SEPARATOR;
    static final String EMPTY;
    static final String[] EMPTY_STRING_ARRAY;
    
    // Core string operations
    static boolean isEmpty(String str);
    static String[] split(String str, char separatorChar);
    static String join(Iterator iterator, String separator);
}

Class Name Utilities

final class ClassUtils {
    // Separator constants
    static final char PACKAGE_SEPARATOR_CHAR;
    static final char INNER_CLASS_SEPARATOR_CHAR;
    
    // Class name operations
    static String getShortClassName(Class cls);
    static String getShortClassName(String className);
}

JAXB Context Management

final class ContextUtils {
    static String getContextPath(Class<?>... classes);
    static String toString(JAXBContext context, Object object);
}

Validation Utilities

final class Validate {
    static void notNull(Object object);
    static void isTrue(boolean expression);
    static void notEmpty(Collection collection);
    static void noNullElements(Collection<?> collection);
}

XML Schema Constants

final class XmlSchemaConstants {
    // XML Schema namespace
    static final String NAMESPACE_URI;
    
    // Built-in type constants
    static final QName ANYTYPE;
    static final QName ANYSIMPLETYPE;
    static final QName STRING;
    static final QName NORMALIZEDSTRING;
    static final QName TOKEN;
    static final QName LANGUAGE;
    static final QName NAME;
    static final QName NCNAME;
    static final QName ID;
    static final QName IDREF;
    static final QName IDREFS;
    static final QName ENTITY;
    static final QName ENTITIES;
    static final QName NMTOKEN;
    static final QName NMTOKENS;
    static final QName BOOLEAN;
    static final QName BASE64BINARY;
    static final QName HEXBINARY;
    static final QName FLOAT;
    static final QName DECIMAL;
    static final QName INTEGER;
    static final QName NONPOSITIVEINTEGER;
    static final QName NEGATIVEINTEGER;
    static final QName LONG;
    static final QName INT;
    static final QName SHORT;
    static final QName BYTE;
    static final QName NONNEGATIVEINTEGER;
    static final QName UNSIGNEDLONG;
    static final QName UNSIGNEDINT;
    static final QName UNSIGNEDSHORT;
    static final QName UNSIGNEDBYTE;
    static final QName POSITIVEINTEGER;
    static final QName DOUBLE;
    static final QName ANYURI;
    static final QName QNAME;
    static final QName NOTATION;
    static final QName DURATION;
    static final QName DATETIME;
    static final QName TIME;
    static final QName DATE;
    static final QName GYEARMONTH;
    static final QName GYEAR;
    static final QName GMONTHDAY;
    static final QName GDAY;
    static final QName GMONTH;
    static final QName CALENDAR;
    
    // Array of all type names
    static final QName[] TYPE_NAMES;
    
    // Utility method
    static QName xsd(String localPart);
}

Usage Examples

String Utilities

import org.jvnet.jaxb2_commons.lang.StringUtils;

// Check for empty/null strings
String value = getInputValue();
if (StringUtils.isEmpty(value)) {
    System.out.println("Input is null or empty");
}

// Split strings by character
String csvData = "apple,banana,cherry,date"; 
String[] fruits = StringUtils.split(csvData, ',');
// Result: ["apple", "banana", "cherry", "date"]

// Join collections with separator
List<String> names = Arrays.asList("John", "Jane", "Bob");
String joined = StringUtils.join(names.iterator(), ", ");
// Result: "John, Jane, Bob"

// Using constants
String[] emptyArray = StringUtils.EMPTY_STRING_ARRAY; // More efficient than new String[0]
String emptyString = StringUtils.EMPTY; // More efficient than ""
String separator = StringUtils.LINE_SEPARATOR; // Platform-specific line separator

Class Name Utilities

import org.jvnet.jaxb2_commons.lang.ClassUtils;

// Get short class names (without package)
Class<?> clazz = java.util.ArrayList.class;
String shortName = ClassUtils.getShortClassName(clazz);
// Result: "ArrayList"

String fullClassName = "com.example.schema.Customer";
String shortClassName = ClassUtils.getShortClassName(fullClassName);
// Result: "Customer"

// Handle inner classes
Class<?> innerClass = Map.Entry.class;
String innerShortName = ClassUtils.getShortClassName(innerClass);
// Result: "Map.Entry"

// Using separator constants
char packageSep = ClassUtils.PACKAGE_SEPARATOR_CHAR; // '.'
char innerSep = ClassUtils.INNER_CLASS_SEPARATOR_CHAR; // '$'

// Custom class name processing
public String getDisplayName(Class<?> clazz) {
    String shortName = ClassUtils.getShortClassName(clazz);
    return shortName.replace(ClassUtils.INNER_CLASS_SEPARATOR_CHAR, '.');
}

JAXB Context Utilities

import org.jvnet.jaxb2_commons.lang.ContextUtils;
import javax.xml.bind.JAXBContext;
import javax.xml.bind.JAXBException;

// Generate context path from classes
Class<?>[] classes = {Customer.class, Order.class, Product.class};
String contextPath = ContextUtils.getContextPath(classes);
// Result: "com.example.schema"

// Create JAXB context using generated path
JAXBContext context = JAXBContext.newInstance(contextPath);

// Marshal object to formatted XML string
Customer customer = new Customer();
customer.setName("John Doe");
customer.setEmail("john@example.com");

String xml = ContextUtils.toString(context, customer);
System.out.println(xml);
/* Output:
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<customer>
    <name>John Doe</name>
    <email>john@example.com</email>
</customer>
*/

// Utility method for creating contexts from multiple packages
public JAXBContext createMultiPackageContext(String... packageNames) throws JAXBException {
    String contextPath = String.join(":", packageNames);
    return JAXBContext.newInstance(contextPath);
}

Validation Utilities

import org.jvnet.jaxb2_commons.lang.Validate;
import java.util.*;

public class CustomerService {
    
    public void createCustomer(String name, String email, List<String> tags) {
        // Validate required parameters
        Validate.notNull(name);
        Validate.notNull(email);
        
        // Validate conditions
        Validate.isTrue(!name.trim().isEmpty());
        Validate.isTrue(email.contains("@"));
        
        // Validate collections
        if (tags != null) {
            Validate.notEmpty(tags);
            Validate.noNullElements(tags);
        }
        
        // Process customer creation...
        System.out.println("Creating customer: " + name);
    }
    
    public void updateCustomer(Customer customer) {
        Validate.notNull(customer);
        Validate.notNull(customer.getId());
        Validate.isTrue(customer.getId() > 0);
        
        // Update logic...
    }
    
    public List<Customer> findCustomers(Collection<Long> customerIds) {
        Validate.notNull(customerIds);
        Validate.notEmpty(customerIds);
        Validate.noNullElements(customerIds);
        
        // Find customers...
        return new ArrayList<>();
    }
}

// Usage examples that would throw exceptions:
try {
    customerService.createCustomer(null, "test@example.com", null);
} catch (IllegalArgumentException e) {
    // "The validated object is null"
}

try {
    customerService.createCustomer("", "test@example.com", null);
} catch (IllegalArgumentException e) {
    // "The validated expression is false"
}

try {
    customerService.findCustomers(Arrays.asList(1L, null, 3L));
} catch (IllegalArgumentException e) {
    // "The validated collection contains null element at index: 1"
}

XML Schema Constants

import org.jvnet.jaxb2_commons.xmlschema.XmlSchemaConstants;
import javax.xml.namespace.QName;

// Using built-in type constants
QName stringType = XmlSchemaConstants.STRING;
QName intType = XmlSchemaConstants.INT;
QName dateType = XmlSchemaConstants.DATE;
QName booleanType = XmlSchemaConstants.BOOLEAN;

// Create custom XSD QNames
QName customType = XmlSchemaConstants.xsd("myCustomType");
// Result: QName with namespace "http://www.w3.org/2001/XMLSchema" and local part "myCustomType"

// Check if a type is a built-in XML Schema type
public boolean isBuiltinType(QName typeName) {
    if (!XmlSchemaConstants.NAMESPACE_URI.equals(typeName.getNamespaceURI())) {
        return false;
    }
    
    for (QName builtin : XmlSchemaConstants.TYPE_NAMES) {
        if (builtin.equals(typeName)) {
            return true;
        }
    }
    return false;
}

// Generate type mapping
public Map<String, QName> createTypeMapping() {
    Map<String, QName> mapping = new HashMap<>();
    mapping.put("string", XmlSchemaConstants.STRING);
    mapping.put("int", XmlSchemaConstants.INT);
    mapping.put("integer", XmlSchemaConstants.INTEGER);
    mapping.put("long", XmlSchemaConstants.LONG);
    mapping.put("double", XmlSchemaConstants.DOUBLE);
    mapping.put("float", XmlSchemaConstants.FLOAT);
    mapping.put("boolean", XmlSchemaConstants.BOOLEAN);
    mapping.put("date", XmlSchemaConstants.DATE);
    mapping.put("dateTime", XmlSchemaConstants.DATETIME);
    mapping.put("time", XmlSchemaConstants.TIME);
    mapping.put("decimal", XmlSchemaConstants.DECIMAL);
    mapping.put("base64Binary", XmlSchemaConstants.BASE64BINARY);
    mapping.put("hexBinary", XmlSchemaConstants.HEXBINARY);
    mapping.put("anyURI", XmlSchemaConstants.ANYURI);
    mapping.put("QName", XmlSchemaConstants.QNAME);
    return mapping;
}

// Validate schema types
public void validateSchemaType(QName typeName) {
    if (XmlSchemaConstants.NAMESPACE_URI.equals(typeName.getNamespaceURI())) {
        if (!isBuiltinType(typeName)) {
            throw new IllegalArgumentException("Unknown XML Schema built-in type: " + typeName.getLocalPart());
        }
    }
}

// Get all available type names
public void printAllTypes() {
    System.out.println("XML Schema built-in types:");
    for (QName type : XmlSchemaConstants.TYPE_NAMES) {
        System.out.println("  " + type.getLocalPart());
    }
}

Combined Utility Usage

import org.jvnet.jaxb2_commons.lang.*;
import org.jvnet.jaxb2_commons.xmlschema.XmlSchemaConstants;

public class SchemaAnalyzer {
    
    public void analyzeClass(Class<?> clazz) {
        // Use ClassUtils for name handling
        String shortName = ClassUtils.getShortClassName(clazz);
        String packageName = clazz.getPackage().getName();
        
        System.out.println("Analyzing class: " + shortName);
        System.out.println("Package: " + packageName);
        
        // Use Validate for parameter checking
        Validate.notNull(clazz);
        Validate.isTrue(!clazz.isInterface());
        
        // Use ContextUtils for JAXB operations
        try {
            String contextPath = ContextUtils.getContextPath(clazz);
            System.out.println("JAXB Context Path: " + contextPath);
        } catch (Exception e) {
            System.out.println("Not a JAXB class: " + e.getMessage());
        }
        
        // Use StringUtils for text processing
        List<String> annotations = getAnnotationNames(clazz);
        if (!annotations.isEmpty()) {
            String annotationList = StringUtils.join(annotations.iterator(), ", ");
            System.out.println("Annotations: " + annotationList);
        }
    }
    
    private List<String> getAnnotationNames(Class<?> clazz) {
        return Arrays.stream(clazz.getAnnotations())
                    .map(annotation -> ClassUtils.getShortClassName(annotation.annotationType()))
                    .collect(Collectors.toList());
    }
    
    public void validateXmlType(QName typeName, Object value) {
        Validate.notNull(typeName);
        
        if (XmlSchemaConstants.NAMESPACE_URI.equals(typeName.getNamespaceURI())) {
            // It's a built-in XML Schema type
            validateBuiltinType(typeName, value);
        } else {
            System.out.println("Custom type: " + typeName);
        }
    }
    
    private void validateBuiltinType(QName typeName, Object value) {
        if (XmlSchemaConstants.STRING.equals(typeName)) {
            Validate.isTrue(value instanceof String);
        } else if (XmlSchemaConstants.INT.equals(typeName)) {
            Validate.isTrue(value instanceof Integer);
        } else if (XmlSchemaConstants.BOOLEAN.equals(typeName)) {
            Validate.isTrue(value instanceof Boolean);
        }
        // ... additional type validations
    }
}

Utility Integration Patterns

These utility classes are designed to work together and integrate seamlessly with the rest of the JAXB2 Basics runtime:

  1. String Processing: StringUtils provides efficient string operations used throughout the library
  2. Class Introspection: ClassUtils supports reflection-based operations and display formatting
  3. JAXB Integration: ContextUtils bridges between Java classes and JAXB contexts
  4. Robust Validation: Validate ensures consistent error handling and parameter validation
  5. Schema Compliance: XmlSchemaConstants provides standard XML Schema type definitions

These utilities form the foundation for higher-level strategic patterns and JAXB integration features.