API Reference

This section provides comprehensive API documentation for all classes and methods in the Blocklist XStream adapter.

Documentation Structure

The API reference is organized into the following sections:

Core Classes

Documentation for the main BlocklistRestrictedXStream class and its core functionality:

• Constructor options and configuration
• Security mode configuration
• Type allowlisting methods
• Converter registration
• Blocked methods for security

Security Classes

Documentation for the security enforcement components:

• BlocklistConverter - High-priority converter that blocks dangerous classes
• BlocklistConverterWrapper - Wraps converters with blocklist checking
• Constants, exception types, and implementation details

Usage Examples

Practical examples and common usage patterns:

• Basic and advanced configuration examples

Quick Reference

Basic Usage

1
2
// Allowlist mode (recommended)
XStream xstream = new BlocklistRestrictedXStream();
xstream.allowTypes(new Class<?>[] { MyClass.class });

// Blocklist mode (migration)
XStream xstream = new BlocklistRestrictedXStream();
xstream.addPermission(AnyTypePermission.ANY);

Key Classes

• BlocklistRestrictedXStream - Main hardened XStream implementation
• BlocklistConverter - Security converter that blocks dangerous classes
• BlocklistConverterWrapper - Wraps local converters with security checks

Main Exceptions

• ForbiddenClassException - Thrown when blocklisted class is encountered
• IllegalArgumentException - Configuration errors (e.g., trying to allow blocklisted class)
• UnsupportedOperationException - Blocked security-unsafe methods

Backwards Compatibility

The adapter maintains full backwards compatibility with standard XStream APIs, with only intentional security restrictions:

• ✅ All standard XStream methods work unchanged
• ✅ Existing aliases, converters, and configurations continue to work
• ❌ High-priority converter registration blocked (security)
• ❌ Wildcard/regex type allowlisting blocked (security)
• ❌ Blocklisted classes cannot be explicitly allowed (security)