8:56 a.m.
Hello,
In Search 6, we are changing the field bridge APIs to move away from Lucene
dependencies. Similarly to the query DSL, this breaks backward
compatibility whatever we do, so we had a look to improving the field
bridge API a bit with some other changes.
The result is we have three types of bridges:
- *ValueBridges* can be applied to values, i.e. either a property value
directly, or container values extracted from the property (list elements,
map keys, ...). They cannot be parameterized and cannot have dedicated
annotations (at least for now), and they are applied to a mapping using
@Field(valueBridge = ...). They are supposed to be applied to simple types
(LocalDate, some Enum, some immutable user type, ...) and perform a 1-1
mapping between the value and a *single* index field. Implementations
are supposed to work as bidirectional functions: one method transforms the
POJO-side type into the Index-side type, and one method does the opposite.
- *TypeBridges* can be applied to types, can be parameterized, they each
have a dedicated annotation (@MyCustomTypeBridge for instance). Their
implementations are supposed to use specific APIs to access both the
property values and the index fields, so that Hibernate Search is aware of
the necessary input data (useful for dirty checking) and of the index
fields created by the bridge, along with their characteristics (field type,
stored or not, analyzer, ...).
- *PropertyBridges* can be applied to properties, can be
parameterized, they each have a dedicated annotation
(@MyCustomPropertyBridge for instance). Their implementations are supposed
to use specific APIs to access both the property values and the index
fields, so that Hibernate Search is aware of the necessary input data
(useful for dirty checking) and of the index fields created by the bridge,
along with their characteristics (field type, stored or not, analyzer, ...).
The expectation is that most users will only need to implement ValueBridge,
which is the simpler one. Users with more advanced needs will be able to
implement TypeBridge/PropertyBridge, which are more complex but are also
much more powerful.
Some aspects of the bridge API are still in the works, so don't be alarmed
to not see them:
- Access to the type/property data in TypeBridge and PropertyBridge is
still a bit rough, missing in particular support for container types (List,
Map, ...).
- During projections, transforming the projected data using bridges is
not supported yet.
The showcase contains a few simple bridge implementations.
- org.hibernate.search.v6poc.integrationtest.showcase.library.bridge.
*ISBNBridge* is a ValueBridge. Hibernate Search is able to detect from
its class metadata that it can only be applied to ISBN values, and
generates a String field.
The bridge is applied using a @Field annotation
on org.hibernate.search.v6poc.integrationtest.showcase.library.model.Book#isbn.
You can find an equivalent use of the bridge in the programmatic mapping
in
org.hibernate.search.v6poc.integrationtest.showcase.library.model.ProgrammaticMappingContributor.
- Another value bridge is applied
to org.hibernate.search.v6poc.integrationtest.showcase.library.model.Library#services
and is implicitly applied to every value of the list.
- org.hibernate.search.v6poc.integrationtest.showcase.library.bridge.
*MultiKeywordStringBridge* is a PropertyBridge which turns a
comma-separated string into multiple field values. It is admittedly a very
simple PropertyBridge, but it has the advantage of showing pretty clearly
how a custom bridge is declared and implemented.
The bridge is applied using its custom "@MultiKeywordStringBridge"
annotation
on org.hibernate.search.v6poc.integrationtest.showcase.library.model.Document#tags.
You can find an equivalent use of the bridge in the programmatic mapping
in
org.hibernate.search.v6poc.integrationtest.showcase.library.model.ProgrammaticMappingContributor:
look for the line where "MultiKeywordStringBridge.Builder" is used.
- org.hibernate.search.v6poc.entity.pojo.bridge.builtin.spatial.
*GeoPointBridge* is a more representative example of what an advanced
bridge could be. It's a built-in bridge, but it could definitely be
implemented by a third-party: no internal APIs are used in its
implementation. Note that one characteristic of this field is that it can
be used both as a TypeBridge or as a PropertyBridge, just as the @Spatial
annotation in Search 5.
The bridge is applied using its dedicated "@GeoPointBridge" annotation
to
type org.hibernate.search.v6poc.integrationtest.showcase.library.model.Library,
with "@Latitude" and "@Longitude" annotations on the relevant
properties of
this type.
You can find an equivalent use of the bridge in the programmatic mapping
in
org.hibernate.search.v6poc.integrationtest.showcase.library.model.ProgrammaticMappingContributor:
look for the line where "GeoPointBridge.Builder" is used, and the lines
where "LatitudeMarker.Builder" and "LongitudeMarker.Builder" are
used.
So, with those few examples of bridges... WDYT?
--
Yoann Rodiere
yoann(a)hibernate.org / yrodiere(a)redhat.com
Software Engineer
Hibernate NoORM team