com.adobe.cq.smartcontent.SmartContentAuthoringService Maven / Gradle / Ivy

/*
 * ADOBE CONFIDENTIAL
 *
 * Copyright 2016 Adobe Systems Incorporated
 * All Rights Reserved.
 *
 * NOTICE:  All information contained herein is, and remains
 * the property of Adobe Systems Incorporated and its suppliers,
 * if any.  The intellectual and technical concepts contained
 * herein are proprietary to Adobe Systems Incorporated and its
 * suppliers and may be covered by U.S. and Foreign Patents,
 * patents in process, and are protected by trade secret or copyright law.
 * Dissemination of this information or reproduction of this material
 * is strictly forbidden unless prior written permission is obtained
 * from Adobe Systems Incorporated.
 */

package com.adobe.cq.smartcontent;

import aQute.bnd.annotation.ProviderType;

import java.util.Locale;

/**
 * This class implements a service that can be used to apply smart content
 * authoring to a text.
 *
 * Language/locale handling:
 *
 * 
 *   An exact match (language + country) is preferred.
 *   If no exact match is found, language data available for the language is chosen.
 *   
 *   If there are neither matches for language and region, nor for language (without
 *   region), a {@link SmartContentException} is thrown.
 * 
 */
@ProviderType
public interface SmartContentAuthoringService {

    /**
     * Determines the language data for the provided {@code Locale}.
     *
     * The method uses the resolution rules stated in the interface's documentation
     * to match over-specific {@code Locale}s to suitable language data.
     *
     * @param locale The locale
     * @return The language data; {@code null} if the specified {@code Locale} is not
     *         supported
     */
    LanguageData getLanguageData(Locale locale);

    /**
     * Creates a summarized version of the provided text.
     *
     * "Summarized" means that the text is reduced to a maximum of the provided number
     * of words. The algorithm will use an algorithm to determine which parts of the
     * original text can be dropped to reach the target length.
     *
     * @param inputString The original text
     * @param outputLen The target length (in words); the actual result may contain less
     *                  words, but not more than specified by this parameter
     * @param language The language of the text, as returned by
     *                 {@link #getLanguageData(Locale)}
     * @return The summarized text
     * @throws SmartContentException if the text could not by summarized, for example if
     *                               required language data (model, dictionaries, ...) were
     *                               missing or an unsupported language was specified
     */
    String summarize(String inputString, int outputLen, LanguageData language) throws SmartContentException;

}