001/*
002 * (C) Copyright 2019 Qastia (http://www.qastia.com/) and others.
003 *
004 * Licensed under the Apache License, Version 2.0 (the "License");
005 * you may not use this file except in compliance with the License.
006 * You may obtain a copy of the License at
007 *
008 *     http://www.apache.org/licenses/LICENSE-2.0
009 *
010 * Unless required by applicable law or agreed to in writing, software
011 * distributed under the License is distributed on an "AS IS" BASIS,
012 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
013 * See the License for the specific language governing permissions and
014 * limitations under the License.
015 *
016 * Contributors:
017 *     Benjamin JALON
018 *
019 */
020
021package org.nuxeo.template.serializer.service;
022
023import java.util.List;
024
025import org.nuxeo.template.api.TemplateInput;
026import org.nuxeo.template.serializer.executors.TemplateSerializer;
027
028/**
029 * Service Exposing serializer and deserializer used to manipulate template rendering data to be injected in the
030 * rendition context. Here are the current service usage :
031 * <ul>
032 * <li>API request =&gt; Inline context preparation : see in
033 * {@link org.nuxeo.template.automation.RenderWithTemplateOperation}</li>
034 * <li>Inline context preparation =&gt; store into the
035 * {@link org.nuxeo.template.api.adapters.TemplateBasedDocument}</li>
036 * <li>Context defined on Template creation =&gt; store into the
037 * {@link org.nuxeo.template.api.adapters.TemplateSourceDocument}</li>
038 * <li>And finally before rendition to collect data from TemplateSource and TemplateBased to generate the global
039 * context</li>
040 * </ul>
041 * You can create your own Serializer contributing to the extension point and call it on the API request. For instance,
042 * if you want to send json instead XML.
043 *
044 * @since 11.1
045 */
046public interface TemplateSerializerService {
047
048    /**
049     * Returns the {@link TemplateSerializer} with the given {@code id}.
050     * <p>
051     * If no {@link TemplateSerializer} is found, return the 'default' one.
052     *
053     * @throws org.nuxeo.ecm.core.api.NuxeoException if no {@code id} or 'default' {@link TemplateSerializer} found
054     */
055    TemplateSerializer getSerializer(String id);
056
057    /**
058     * Convenient method to serialize {@code params} to XML using the 'xml' {@link TemplateSerializer}.
059     */
060    default String serializeXML(List<TemplateInput> params) {
061        return getSerializer("xml").serialize(params);
062    }
063
064    /**
065     * Convenient method to deserialize XML content using the 'xml' {@link TemplateSerializer}..
066     */
067    default List<TemplateInput> deserializeXML(String content) {
068        return getSerializer("xml").deserialize(content);
069    }
070
071}