org.apache.abdera.model.Categories Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of aem-sdk-api Show documentation
The Adobe Experience Manager SDK
There is a newer version: 2024.11.18751.20241128T090041Z-241100
/*
 * Licensed to the Apache Software Foundation (ASF) under one or more
 * contributor license agreements.  The ASF licenses this file to You
 * under the Apache License, Version 2.0 (the "License"); you may not
 * use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.  For additional information regarding
 * copyright in this work, please see the NOTICE file in the top level
 * directory of this distribution.
 */
package org.apache.abdera.model;

import java.util.List;
import org.apache.abdera.i18n.iri.IRI;

/**
 *  The Atom Publishing Protocol introduces the notion of a "Category Document" and the app:categories element. These are
 *  used to provide a listing of atom:category elements that may be used with the members of an Atom Publishing Protocol
 *  collection.
 *
 * @deprecated This API is deprecated as Apache Abdera is a retired project since 2017.
 */
@Deprecated(since = "2021-07-29")
public interface Categories extends ExtensibleElement {

    /**
     * When contained within an app:collection element, the app:categories element can have an href attribute whose
     * value MUST point to an Atompub Categories Document.
     *
     * @return The href attribute value
     */
    IRI getHref();

    /**
     * Returns the value of the href attribute resolved against the in-scope Base URI
     *
     * @return The fully resolved href attribute value
     */
    IRI getResolvedHref();

    /**
     * Sets the value of the href attribute.
     *
     * @param href The location of an Atompub Categories Document
     */
    Categories setHref(String href);

    /**
     * If an app:categories element is marked as fixed, then the set of atom:category elements is considered to be a
     * closed set. That is, Atom Publishing Protocol clients SHOULD only use the atom:category elements listed. The
     * default is false (fixed="no")
     *
     * @return True if the categories listing is fixed
     */
    boolean isFixed();

    /**
     * Sets whether or not this is a fixed listing of categories. If set to false, the fixed attribute will be removed
     * from the app:categories element.
     *
     * @param fixed True if the app:categories listing is fixed
     */
    Categories setFixed(boolean fixed);

    /**
     * The app:categories element may specify a default scheme attribute for listed atom:category elements that do not
     * have their own scheme attribute.
     *
     * @return The scheme IRI
     */
    IRI getScheme();

    /**
     * Sets the default scheme for this listing of categories
     *
     * @param scheme The default scheme used for this listing of categories
     */
    Categories setScheme(String scheme);

    /**
     * Lists the complete set of categories
     *
     * @return This app:categories listing of atom:category elements
     */
    List getCategories();

    /**
     * Lists the complete set of categories that use the specified scheme
     *
     * @param scheme The IRI of an atom:category scheme
     * @return A listing of atom:category elements that use the specified scheme
     */
    List getCategories(String scheme);

    /**
     * Returns a copy of the complete set of categories with the scheme attribute set
     *
     * @return A listing of atom:category elements using the default scheme specified by the app:categories scheme
     *         attribute
     */
    List getCategoriesWithScheme();

    /**
     * Returns a copy of the complete set of categories with the scheme attribute set as specified in 7.2.1. (child
     * categories that do not have a scheme attribute inherit the scheme attribute of the parent)
     *
     * @param scheme A scheme IRI
     * @return A listing of atom:category elements
     */
    List getCategoriesWithScheme(String scheme);

    /**
     * Add an atom:category to the listing
     *
     * @param category The atom:category to add to the listing
     */
    Categories addCategory(Category category);

    /**
     * Create and add an atom:category to the listing
     *
     * @param term The string term
     * @return The newly created atom:category
     */
    Category addCategory(String term);

    /**
     * Create an add an atom:category to the listing
     *
     * @param scheme The scheme IRI for the newly created category
     * @param term The string term
     * @param label The human readable label for the category
     * @return The newly created atom:category
     */
    Category addCategory(String scheme, String term, String label);

    /**
     * Returns true if this app:categories listing contains a category with the specified term
     *
     * @param term The term to look for
     * @return True if the term is found
     */
    boolean contains(String term);

    /**
     * Returns true if this app:categories listing contains a category with the specified term and scheme
     *
     * @param term The term to look for
     * @param scheme The IRI scheme
     * @return True if the term and scheme are found
     */
    boolean contains(String term, String scheme);

    /**
     * Returns true if the href attribute is set
     */
    boolean isOutOfLine();
}