org.apache.abdera.model.Collection 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 javax.activation.MimeType;
import org.apache.abdera.i18n.iri.IRI;

/**
 *  
 *  Represents an collection element in an Atom Publishing Protocol introspection document.
 *  
 *
 *   *   The "app:collection" describes an Atom Protocol collection.  One
 *   child element is defined here for app:collection: "app:member-type".
 *
 *   appCollection =
 *      element app:collection {
 *         appCommonAttributes,
 *         attribute href { text },
 *         ( atomTitle
 *           & appAccept
 *           & extensionElement* )
 *      }
 *  
 *
 * @deprecated This API is deprecated as Apache Abdera is a retired project since 2017.
 */
@Deprecated(since = "2021-07-29")
public interface Collection extends ExtensibleElement {

    /**
     * The text value of the collections atom:title element
     *
     * @return The atom:title value
     */
    String getTitle();

    /**
     * Set the value of the collections atom:title element using type="text"
     *
     * @param title The value of the atom:title
     * @return The newly created title element
     */
    Text setTitle(String title);

    /**
     * Set the value of the collections atom:title element using type="html". Special characters in the value will be
     * automatically escaped (e.g. & will become &
     *
     * @param title The value of the atom:title
     * @return The newly created title element
     */
    Text setTitleAsHtml(String title);

    /**
     * Set the value of the collections atom:title element using type="xhtml". The title text will be wrapped in a
     * xhtml:div and parsed to ensure that it is welformed XML. A ParseException (RuntimeException) could be thrown
     *
     * @param title The value of the atom:title
     * @return The newly created title element
     */
    Text setTitleAsXHtml(String title);

    /**
     * Return the title element
     *
     * @return The title element
     */
    Text getTitleElement();

    /**
     * Return the value of the app:collection elements href attribute
     *
     * @return The href attribute IRI value
     * @throws IRISyntaxException if the value of the href attribute is malformed
     */
    IRI getHref();

    /**
     * Return the href attribute resolved against the in-scope Base URI
     *
     * @return The href attribute IRI value
     * @throws IRISyntaxException if the value of the href attribute is malformed
     */
    IRI getResolvedHref();

    /**
     * Set the value of the href attribute
     *
     * @param href The value of href attribute
     * @throws IRISyntaxException if the href attribute is malformed
     */
    Collection setHref(String href);

    /**
     * Returns the listing of media-ranges allowed for this collection
     *
     * @return An array listing the media-ranges allowed for this collection
     */
    String[] getAccept();

    /**
     * Set the listing of media-ranges allowed for this collection. The special value "entry" is used to indicate Atom
     * Entry Documents.
     *
     * @param mediaRanges a listing of media-ranges
     * @throws MimeTypeParseException
     */
    Collection setAccept(String... mediaRanges);

    /**
     * Returns true if the collection accepts the given media-type
     *
     * @param mediaType The media-type to check
     * @return True if the media-type is acceptable
     */
    boolean accepts(String mediaType);

    /**
     * Returns true if the collection accepts Atom entry documents (equivalent to calling
     * accepts("application/atom+xml;type=entry");)
     */
    boolean acceptsEntry();

    /**
     * Returns true if the collection accepts nothing (i.e. there is an empty accept element)
     */
    boolean acceptsNothing();

    /**
     * Sets the appropriate accept element to indicate that entries are accepted (equivalent to calling
     * setAccept("application/atom+xml;type=entry");)
     */
    Collection setAcceptsEntry();

    /**
     * Sets the collection so that nothing is accepted (equivalent to calling setAccept(""); )
     */
    Collection setAcceptsNothing();

    /**
     * Adds a new accept element to the collection
     */
    Collection addAccepts(String mediaRange);

    /**
     * Adds new accept elements to the collection
     */
    Collection addAccepts(String... mediaRanges);

    /**
     * Same as setAcceptsEntry except the existing accepts are not discarded
     */
    Collection addAcceptsEntry();

    /**
     * Returns true if the collection accepts the given media-type
     *
     * @param mediaType The media-type to check
     * @return True if the media-type is acceptable
     */
    boolean accepts(MimeType mediaType);

    /**
     * Returns the app:categories element
     *
     * @return The app:categories element
     */
    List getCategories();

    /**
     * Add an app:categories element
     *
     * @return The newly created app:categories element
     */
    Categories addCategories();

    /**
     * Add an app:categories element that links to an external Category Document
     *
     * @param href The IRI of the external Category Document
     * @return The newly created app:categories element
     */
    Categories addCategories(String href);

    /**
     * Add the app:categories element to the collection
     *
     * @param categories The app:categories element
     */
    Collection addCategories(Categories categories);

    /**
     * Add a listing of categories to the collection
     *
     * @param categories The listing of categories to add
     * @param fixed True if the listing of categories should be fixed
     * @param scheme The default IRI scheme for the categories listing
     * @return The newly created app:categories element
     */
    Categories addCategories(List categories, boolean fixed, String scheme);
}