Skip to content

README.md

Latest commit

 

History

History
269 lines (202 loc) · 9.62 KB

README.md

File metadata and controls

269 lines (202 loc) · 9.62 KB

commons-java

Foundation utilities for the Solenopsis Salesforce SOAP framework.

Build Status codecov License: GPL v3 Security Policy Maven Central Java Version Coverage Quality

Purpose

This library provides low-level utilities used by the Solenopsis framework for Salesforce SOAP operations:

  • solenopsis/soap - Salesforce SOAP client generation (Apex, Metadata, Enterprise, Partner, Tooling APIs)
  • solenopsis/session - Salesforce session management and authentication

Features

SOAP Utilities (org.flossware.commons-java.util.SoapUtil)

Core utilities for Apache CXF SOAP clients:

  • Configure SOAP service headers and endpoints
  • Compute QNames from @WebServiceClient annotations
  • Set custom headers for Salesforce API calls
  • Manage SOAP factory instances

String Utilities (org.flossware.commons-java.util.StringUtil)

  • String concatenation with separators
  • URL encoding
  • Unique ID generation with UUID
  • Validation (requireNonBlank)
  • Serialization/deserialization (internal use only)

File Utilities (org.flossware.commons-java.util.FileUtil)

  • Safe file I/O with validation
  • File existence checking
  • FileInputStream creation with proper error handling

Additional Utilities

  • ArrayUtil - Array validation and null-checking
  • ClassUtil - Reflection and package utilities
  • LoggerUtil - Enhanced logging with varargs support
  • ObjectUtil - Object validation helpers
  • UrlUtil - URL parsing and manipulation

Installation

Maven

<dependency>
    <groupId>org.flossware</groupId>
    <artifactId>commons-java</artifactId>
    <version>LATEST</version> <!-- Check releases: https://github.com/FlossWare/commons-java/releases -->
</dependency>

<repositories>
    <repository>
        <id>flossware-packagecloud</id>
        <url>https://packagecloud.io/flossware/java/maven2</url>
    </repository>
</repositories>

Usage Examples

Configure Salesforce SOAP Endpoint

import org.flossware.commons-java.util.SoapUtil;

// Create a port and set Salesforce endpoint
MetadataPortType port = portFactory.createPort();
SoapUtil.setUrl(port, "https://na1.salesforce.com/services/Soap/m/58.0");

Set SOAP Headers for Salesforce Session

import org.flossware.commons-java.util.SoapUtil;
import javax.xml.namespace.QName;

Service service = new MetadataService();
QName sessionHeaderQName = new QName("http://soap.sforce.com/2006/04/metadata", "SessionHeader");

SoapUtil.setHeader(service, sessionHeaderQName, sessionHeaderValue);

Compute QName from Service Class

import org.flossware.commons-java.util.SoapUtil;

QName qname = SoapUtil.computeQName(MetadataService.class);
// Returns QName based on @WebServiceClient annotation

String Validation

import org.flossware.commons-java.util.StringUtil;

// Validate non-blank strings
String apiUrl = StringUtil.requireNonBlank(url, "Salesforce URL cannot be blank");

// Generate unique IDs
String requestId = StringUtil.generateUniqueString("sfdc-request-");

File Operations

import org.flossware.commons-java.util.FileUtil;

// Ensure file exists before processing
File wsdlFile = FileUtil.ensureFileExists("src/main/resources/wsdl/metadata.wsdl");

// Safe file input stream creation
FileInputStream fis = FileUtil.getFileInputStream(deploymentPackage);

Requirements

  • Java 17+
  • Apache CXF 4.0+ - For SOAP client support
  • Apache Commons Lang3 3.17+ - Baseline utilities

Building

# Build and run tests
mvn clean install

# Run tests only
mvn test

# Skip tests
mvn clean install -DskipTests

Test Coverage

The library maintains excellent test coverage with 307 tests (287 unit + 20 integration):

Coverage Metrics:

  • 🎯 93% instruction coverage (1,453/1,562 instructions)
  • ✅ 86% branch coverage (83/96 branches)
  • 🎯 93% method coverage (126/135 methods)
  • 🎯 93% line coverage (351/376 lines)
  • 🎯 100% class coverage (19/19 classes)

Test Suite Includes:

  • Input validation edge cases (null, empty, whitespace)
  • Exception handling verification (including defensive paths)
  • SOAP utilities with Mockito-based integration tests
  • String operations, encoding, and serialization
  • File operations with temporary files
  • Reflection-based tests for private constructors and utility class enforcement
  • Mock-based tests for unreachable exception paths
  • Defensive code validation via reflection
  • ObjectInputFilter comprehensive security testing:
    • ALLOWED path: trusted packages (org.flossware., java.lang., java.util.*, arrays)
    • REJECTED path: untrusted packages with warning logging
    • UNDECIDED path: null serialClass during metadata processing
  • Complex object graph deserialization (ArrayList, nested structures)

All 265 tests pass with 0 failures. JaCoCo coverage reports are generated with each build.

Remaining Branch Coverage (3 of 96 branches, 96%):

  • Minor edge cases in conditional logic - represents truly exceptional coverage

Architecture

This library sits at the foundation of the Solenopsis stack:

┌─────────────────────────┐
│  Solenopsis Session     │  ← Authentication & session mgmt
└───────────┬─────────────┘
            │ depends on
┌───────────▼─────────────┐
│  Solenopsis SOAP        │  ← Salesforce API clients
└───────────┬─────────────┘
            │ depends on
┌───────────▼─────────────┐
│  commons-java               │  ← Foundation utilities (this)
└─────────────────────────┘

Security Considerations

For security vulnerability reporting, see SECURITY.md.

Java Serialization

The serialization methods in StringUtil are for internal use only:

  • WARNING: Java deserialization of untrusted data is a security risk
  • Only deserialize data from trusted sources
  • Consider using JSON or XML for external data
  • These methods are used internally for session caching
  • ObjectInputFilter protection added in v1.30 to restrict deserialization to trusted packages

Deprecation Notice

Several methods are deprecated and scheduled for removal in version 2.0:

StringUtil Serialization Methods (Deprecated since v1.22)

  • toString(Serializable) - Use JSON libraries (Jackson, Gson) instead
  • fromString(String) - Use JSON libraries (Jackson, Gson) instead
  • toCompressedString(Serializable) - Use JSON with compression instead
  • fromCompressedString(String) - Use JSON with decompression instead

Migration Example:

// Old (deprecated)
String serialized = StringUtil.toString(myObject);
MyClass obj = StringUtil.fromString(serialized);

// New (recommended)
ObjectMapper mapper = new ObjectMapper();
String json = mapper.writeValueAsString(myObject);
MyClass obj = mapper.readValue(json, MyClass.class);

FileUtil Methods (Check JavaDoc for deprecation status)

  • getFileInputStream(File) - Use Files.newInputStream(Path) instead
  • getFileInputStream(String) - Use Files.newInputStream(Path) instead
  • ensureFileExists(File) - Use Files.exists(Path) with proper exception handling
  • ensureFileExists(String) - Use Files.exists(Path) with proper exception handling

StringUtil Validation Methods

  • ensureString(String) - Use requireNonBlank(String) instead
  • ensureString(String, String) - Use requireNonBlank(String, String) instead

Timeline:

  • v1.x: Current stable branch (security fixes and critical bugs only)
  • v2.0: Planned removal of all deprecated methods

See CHANGELOG.md for detailed migration guide.

Contributing

See CONTRIBUTING.md for detailed guidelines including:

  • Code style and standards (Google Java Style Guide)
  • Testing requirements (93% coverage minimum)
  • Pull request process
  • Commit message format

Quick start:

  1. Fork and clone the repository
  2. Run mvn verify to ensure all tests pass
  3. Make changes following our coding standards
  4. Submit PR with tests and documentation

License

GNU General Public License, Version 3 - See LICENSE file

Links

Version History

See CHANGELOG.md for detailed version history.