REST Api: Refactor Marshaller (static methods -> components)

Broken compatibilities (details is below): With a way to get the previous behaviour: DocumentModel to Json: versionLabel/lock removed Json to DocumentModel: "" strings is recognized as empty and not null as previous behaviour Document json loaded schema: header 'X-NXDocumentProperties' is replaced by header 'X-NXproperties' header or 'properties' http GET parameter but still supported Document json Enrichers: header 'X-NXContext-Category' is replaced by header 'X-NXenrichers.document' header or 'enrichers.document' http GET parameter but still supported Without any way to get the previous behaviour: REST API: Move org.nuxeo.ecm.restapi.jaxrs.io.directory.DirectoryEntry to nuxeo-platform-directory-api: org.nuxeo.ecm.directory.api.DirectoryEntry Automation: Move org.nuxeo.ecm.automation.jaxrs.io.audit.LogEntryList to nuxeo-platform-audit-api: org.nuxeo.ecm.platform.audit.api.LogEntryList Automation: ContentEnricherService removed and replaced by Marshaller implementing AbstractJsonEnricher<EntityType> : the behaviour is the same (existing enrichers still work) but customer's extension must be migrated. Plus enricher parameters are not yet supported. Was used for: VocabularyEnricher: specific enricher wrote for nuxeo-platform-spreadsheet project UserPermissionsContentEnricher Read|Write|Everything hard coded cutom fields / ObjectResolver : Add a new method to resolver which returns the classes managed by the fetching: org.nuxeo.ecm.core.schema.types.resolver.ObjectResolver.getManagedClasses() Directory custom field: DirectoryEntryResolver fetch org.nuxeo.ecm.directory.api.DirectoryEntry instead of DocumentModel (explicit typing) -------------------------------------------------------------------- Existing JSON Marshalling: Old marshalling format is maintained except: BROKEN COMPATIBILITY # Changes for DocumentModel -> JSON: Document Version and Lock info are not anymore fetched by default > force fetching using system properties nuxeo.document.json.fetch.heavy=true > force fetching using HEADER X-NXfetch.document=versionLabel or X-NXfetch.document=lock > force fetching using GET parameter fetch.document=versionLabel or fetch.document=lock > force fetching using Changes for JSON -> DocumentModel: inputs must be well typed: string for boolean or int are not accepted anymore empty string properties "" are recognized as empty "" insted of null like previous behaviour Old reader is usable by setting system property nuxeo.document.json.legacy=true or by adding a http header to the request: X-NXDocumentJsonLegacy=true -------------------------------------------------------------------- New JSON Marshalling features: Contribute to marshalling Write an class extending org.nuxeo.ecm.core.io.registry.Writer<EntityType> or org.nuxeo.ecm.core.io.registry.Reader<EntityType> Use @Setup(mode, priority) to specifiy the instantiation mode of your marshaller (singleton, per thread, each use instantiation) Use @Supports(MediaType) annotation to specify the format (MediaType.APPLICATION_JSON for Json) !!! Unlike JAX-RS the full generic type is used to manage the activation of the marshaller: if you create a Writer<Map<String, DocumentModel>> marshaller, it will be enable only for JAX-RS web method returning objects implementing Map<String, DocumentModel> (JAX-RS just supports Map matching in this case). There's no need to override the accept method in this case. Please prefer use abstract classes (this will facilitates the writing of your marshaller): org.nuxeo.ecm.core.io.marshallers.json.AbstractJsonWriter<EntityType> : optimized base for Java to JSON org.nuxeo.ecm.core.io.marshallers.json.ExtensibleEntityJsonWriter<EntityType> : extensible named entity Java to JSON org.nuxeo.ecm.core.io.marshallers.json.DefaultListJsonWriter<EntityType> : list of 'Json-Writable' objects org.nuxeo.ecm.core.io.marshallers.json.AbstractJsonReader<EntityType> : optimized base for JSON to Java org.nuxeo.ecm.core.io.marshallers.json.EntityJsonReader<EntityType> : named entity JSON reader org.nuxeo.ecm.core.io.marshallers.json.DefaultListJsonReader<EntityType> : list of 'Json-Readable' objects Extension point example: <component name="org.nuxeo.ecm.platform.usermanager.marshallers" version="1.0.0"> <documentation> Core IO registered marshallers set. </documentation> <extension target="org.nuxeo.ecm.core.io.MarshallerRegistry" point="marshallers"> <register class="org.nuxeo.ecm.platform.usermanager.io.NuxeoPrincipalJsonWriter" enable="true" /> <register class="org.nuxeo.ecm.platform.usermanager.io.NuxeoPrincipalJsonReader" enable="true" /> <register class="org.nuxeo.ecm.platform.usermanager.io.NuxeoPrincipalListJsonWriter" enable="true" /> <register class="org.nuxeo.ecm.platform.usermanager.io.NuxeoPrincipalListJsonReader" enable="true" /> <register class="org.nuxeo.ecm.platform.usermanager.io.NuxeoGroupJsonWriter" enable="true" /> <register class="org.nuxeo.ecm.platform.usermanager.io.NuxeoGroupJsonReader" enable="true" /> <register class="org.nuxeo.ecm.platform.usermanager.io.NuxeoGroupListJsonWriter" enable="true" /> <register class="org.nuxeo.ecm.platform.usermanager.io.NuxeoGroupListJsonReader" enable="true" /> </extension> </component> All Core IO marshallers are usable in WebEngine projects You just have to add this MessabeBodyWriter/MessageBodyReader to your application: org.nuxeo.ecm.webengine.jaxrs.coreiodelegate.FullCoreIODelegate You can customize the delegation using org.nuxeo.ecm.webengine.jaxrs.coreiodelegate.PartialCoreIODelegate Or write your own delegation Be careful: JAX-RS Marshallers have a greater priority than core io marshallers (if a DocumentModel MessageBodyWriter is present in your project, it will be used in priority) Marshaller overriding: You can define your own core-io marshallers and override existing marshalling To achieve that, create a core-io Reader/Writer with a higher priority (Nuxeo base marshallers priority is 2000 -> Priorities.REFERENCE): @Setup(mode = Instantiations.SINGLETON, priority = Priorities.OVERRIDE_REFERENCE) public class MyCustomNuxeoPrincipalJsonWriter implements Writer<NuxeoPrincipal> { ... } Most of existing marshallers could be extended using enrichers (see below) or by extending the existing writer and implementing method 'extend' @Setup(mode = Instantiations.SINGLETON, priority = Priorities.OVERRIDE_REFERENCE) public class MyCustomNuxeoPrincipalJsonWriter extends NuxeoPrincipalJsonWriter Unknown macro: { protected void extend(EntityType entity, JsonWriter jg) throws IOException { ... } } => this will add extra JSON info in exiting JSON and will preserve compatibility with existing API Properties loading: Old header X-NXDocumentProperties is still supported You may use alternative parameter properties=* or properties=dublincore,common or ?properties=dublincore&properties=common or header X-NXproperties=dublincore,common Enrichment: Available for 'Json-Writable' entities: DocumentModel, ACL, DocumentType, Schema, Facet, Constraint, DocumentValidationReport, NuxeoPrincipal, NuxeoGroup, Directory, LogEntry The corresponding marshaller supports Enrichers. You have to write and register in core-io a class extendind AbstractJsonEnricher<EntityType> where EntityType is the original Marshalled type This will add an aditionnal Json property 'contextParameters' which will contain all related enrichers. Enrichers is not enable by default, you have to add a paremeter or header in your request: > Parameter: enrichers.document=children,acls > Header: X-NXenrichers.document=children,acls This supports and will aggregate multiple parameters or headers: ?enrichers.document=children&enrichers.document=acls This supports old header X-NXContext-Category To enrich a NuxeoPrincipal with your own enricher 'userComputedInfos', you have to put the parameter enrichers.user=userComputedInfos Fetching: When you defined some document's properties as a reference to an object using an ObjectResolver (contrib to component org.nuxeo.ecm.core.schema.ObjectResolverService, extension point 'resolvers'), you can fetch the corresponding object if the Json reader and Json writer are available (this is the case for DocumentModel, Directory, NuxeoPrincipal and NuxeoGroup properties). To enable the fetching, use the parameter fetch.document=properties => this will fetch all properties or with a specific property path : fetch.document=mySchema:users/user [0] /nuxeoPrincipalId => this will fetch the property nuxeoPrincipalId or the first user of the user list property users or with a generic path : fetch.document=mySchema:user:users/user/nuxeoPrincipalId => this will fetch all property nuxeoPrincipalId or with a parent path : fetch.document=mySchema:users => this will fetch all fetchable properties under users !!! The property value is accepted in Json by the reader and the corresponding object too (you can use either the reference or the object to update your document) -------------------------------------------------------------------- Distribution Tomcat: Add new library commons-lang3 in ${distribution.dir}/lib" -------------------------------------------------------------------- Nuxeo pom.xml: Add dependency management for nuxeo-core-io test-jar Add dependency management for commons-lang3 -------------------------------------------------------------------- Query API: Move most of object of the package nuxeo-platform-query-api: org.nuxeo.ecm.platform.query.api in nuxeo-core-query project SAME PACKAGE USED org.nuxeo.ecm.platform.query.api.Aggregate org.nuxeo.ecm.platform.query.api.AggregateDefinition org.nuxeo.ecm.platform.query.api.AggregateRangeDateDefinition org.nuxeo.ecm.platform.query.api.AggregateRangeDefinition org.nuxeo.ecm.platform.query.api.Bucket org.nuxeo.ecm.platform.query.api.PageProvider org.nuxeo.ecm.platform.query.api.PageProviderChangedListener org.nuxeo.ecm.platform.query.api.PageProviderDefinition org.nuxeo.ecm.platform.query.api.PageSelection org.nuxeo.ecm.platform.query.api.PageSelections org.nuxeo.ecm.platform.query.api.PredicateDefinition org.nuxeo.ecm.platform.query.api.PredicateFieldDefinition org.nuxeo.ecm.platform.query.api.WhereClauseDefinition Move nuxeo-platform-search-api: org.nuxeo.ecm.core.search.api.client.querymodel.Escaper in nuxeo-core-query project SAME PACKAGE USED org.nuxeo.ecm.core.search.api.client.querymodel.Escaper -------------------------------------------------------------------- Web Engine: Add exception handling for DocumentValidationException and mediatype 'application/json' Add maven and bundle dependency to nuxeo-core-io Add a converter from javax.servlet.http.HttpServletRequest to nuxeo-core-io RenderingContext (request parameters, attributes and headers) Add JAX-RS MessageBodyReader/MessageBodyWriter that delegates marshalling to nuxeo-core-io MarshallerRegistry: org.nuxeo.ecm.webengine.jaxrs.coreiodelegate.FullCoreIODelegate org.nuxeo.ecm.webengine.jaxrs.coreiodelegate.PartialCoreIODelegate Ugly copy of VirtualHostHelper: // TODO: refactor with org.nuxeo.ecm.platform.web.common.vh.VirtualHostHelper Add "org.nuxeo.ecm.core.io" bundle to WebEngineFeature test's feature -------------------------------------------------------------------- Rest API v1: BROKEN COMPATIBILITY: Move org.nuxeo.ecm.restapi.jaxrs.io.directory.DirectoryEntry to nuxeo-platform-directory-api: org.nuxeo.ecm.directory.api.DirectoryEntry -------------------------------------------------------------------- Automation: BROKEN COMPATIBILITY: Move org.nuxeo.ecm.automation.jaxrs.io.audit.LogEntryList to nuxeo-platform-audit-api: org.nuxeo.ecm.platform.audit.api.LogEntryList Move 4 Pagination related objects to nuxeo-core-io project SAME PACKAGE USED org.nuxeo.ecm.automation.core.util.Paginable<T> org.nuxeo.ecm.automation.core.util.PaginablePageProvider<T> org.nuxeo.ecm.automation.core.util.PaginableDocumentModelList org.nuxeo.ecm.automation.jaxrs.io.documents.PaginableDocumentModelListImpl contrib marshaller-contrib.xml : Remove <writer>org.nuxeo.ecm.automation.jaxrs.io.documents.JsonDocumentWriter</writer> <writer>org.nuxeo.ecm.automation.jaxrs.io.documents.JsonDocumentListWriter</writer> <writer>org.nuxeo.ecm.automation.jaxrs.io.audit.LogEntryWriter</writer> <writer>org.nuxeo.ecm.automation.jaxrs.io.audit.LogEntryListWriter</writer> contrib marshaller-contrib.xml : Add <writer>org.nuxeo.ecm.webengine.jaxrs.coreiodelegate.FullCoreIODelegate</writer> BROKEN COMPATIBILITY: ContentEnricherService remove extension point - maintain feature - existing marshallers migrated Remove the service - replace all enrichers by custom marshallers class extending: org.nuxeo.ecm.core.io.marshallers.json.enrichers.AbstractJsonEnricher<EntityType> (class used by marshallers extending org.nuxeo.ecm.core.io.marshallers.json.ExtensibleEntityJsonWriter<EntityType>) New marshallers: nuxeo-core-io: org.nuxeo.ecm.core.io.marshallers.json.enrichers.ACLJsonEnricher nuxeo-core-io: org.nuxeo.ecm.core.io.marshallers.json.enrichers.BasePermissionsJsonEnricher nuxeo-core-io: org.nuxeo.ecm.core.io.marshallers.json.enrichers.BreadcrumbJsonEnricher nuxeo-core-io: org.nuxeo.ecm.core.io.marshallers.json.enrichers.ChildrenJsonEnricher nuxeo-core-io: org.nuxeo.ecm.core.io.marshallers.json.enrichers.ContextualParametersJsonEnricher nuxeo-platform-url-core: org.nuxeo.ecm.platform.url.io.DocumentUrlJsonEnricher nuxeo-platform-preview: org.nuxeo.ecm.platform.preview.io.PreviewJsonEnricher nuxeo-platform-ui-web: org.nuxeo.ecm.platform.ui.web.io.ThumbnailJsonEnricher nuxeo-platform-spreadsheet: org.nuxeo.ecm.platform.spreadsheet.DCVocabulariesJsonEnricher New enrichers are enable by their projects using contrib to nuxeo-core-io MarshallerRegistry: <?xml version="1.0"?> <component name="org.nuxeo.ecm.platform.spreadsheet.marshallers" version="1.0.0"> <documentation> Core IO registered marshallers set. </documentation> <extension target="org.nuxeo.ecm.core.io.MarshallerRegistry" point="marshallers"> <!-- vocabularies dublincore document enricher --> <register class="org.nuxeo.ecm.platform.spreadsheet.DCVocabulariesJsonEnricher" enable="true" /> </extension> </component> -------------------------------------------------------------------- Core Extended fields (updates of initial NXP-15975 ) : BROKEN COMPATIBILITY: DirectoryEntryResolver fetch org.nuxeo.ecm.directory.api.DirectoryEntry instead of DocumentModel (explicit typing) BROKEN COMPATIBILITY: Add a new method to resolver which returns the classes managed by the fetching: org.nuxeo.ecm.core.schema.types.resolver.ObjectResolver.getManagedClasses() + implementation for UserManagerResolver (NuxeoPrincipal.class and NuxeoGroup.class), DocumentModelResolver (DocumentModel.class), DirectoryEntryResolver (DirectoryEntry.class) Handle exceptions on message error generation when there's no i18n properties file DocumentValidationReport constructor is now public --------------------------------------------------------------------