Module org.seasar.doma.core

Package org.seasar.doma.internal.jdbc.entity

Interface PropertyPathSegment

All Known Implementing Classes:

PropertyPathSegment.Default, PropertyPathSegment.Optional

public interface PropertyPathSegment

Represents a single segment within a property path that defines how to access a field.

A property path segment encapsulates the logic for accessing a specific field within an object, including handling different field types such as regular fields and optional fields. Each segment knows its name and how to create a FieldWrapper for accessing the corresponding field.

This interface provides different implementations for different field access patterns:

• PropertyPathSegment.Default - for regular field access with direct value retrieval and assignment
• PropertyPathSegment.Optional - for optional field access that unwraps Optional values and provides transparent access to the contained value

Usage: Property path segments are typically used in conjunction with PropertyPath to build chains of field access operations. Each segment represents one level in the property navigation chain, such as address.street.name where each dot-separated part corresponds to a segment.

Thread Safety: Implementations of this interface should be immutable and thread-safe. The provided record implementations (PropertyPathSegment.Default and PropertyPathSegment.Optional) are inherently thread-safe due to their immutable nature.

Reflection Handling: Implementations handle reflection-based field access internally, including making private fields accessible when necessary. Callers do not need to manage field accessibility.

This interface is used internally by the Doma framework for property mapping and should not be used directly by application code.

Since:

2.0.0

See Also:

• PropertyPath
• FieldWrapper

Nested Class Summary

Nested Classes

Modifier and Type	Interface	Description
static final record	PropertyPathSegment.Default	A default property path segment implementation for regular field access.
static final record	PropertyPathSegment.Optional	A property path segment implementation for optional field access.

Method Summary

Modifier and Type	Method	Description
String	name()	Returns the name of this property path segment.
FieldWrapper	wrapField(Field field)	Creates a field wrapper for the specified field that handles access according to this segment's type.

Method Details

name

String name()

Returns the name of this property path segment.

The name typically corresponds to a field name in a Java class and is used for identification and debugging purposes. For example, in a property path like person.address.street, each segment would have names "person", "address", and "street" respectively.

Returns:

the segment name, never null for well-formed segments

wrapField

FieldWrapper wrapField(Field field)
                throws WrapException

Creates a field wrapper for the specified field that handles access according to this segment's type.

The field wrapper will be configured to handle the specific access pattern required by this segment type. For example:

• PropertyPathSegment.Default segments create wrappers for direct field access
• PropertyPathSegment.Optional segments create wrappers that automatically unwrap Optional values

The implementation automatically handles field accessibility, making private fields accessible as needed. The returned wrapper provides a consistent interface for field access regardless of the underlying field's visibility modifiers.

Parameters:

field - the field to wrap, must not be null

Returns:

a field wrapper configured for this segment's access pattern, never null

Throws:

WrapException - if an error occurs while creating the wrapper, such as security restrictions preventing field access

IllegalArgumentException - if the field type is incompatible with this segment type (implementation-specific)