Re: [hibernate-dev] [HSEARCH][V6-POC] FieldBridge 2.0

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