001/**
002 * #-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=#
003 *   This file is part of the LDP4j Project:
004 *     http://www.ldp4j.org/
005 *
006 *   Center for Open Middleware
007 *     http://www.centeropenmiddleware.com/
008 * #-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=#
009 *   Copyright (C) 2014-2016 Center for Open Middleware.
010 * #-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=#
011 *   Licensed under the Apache License, Version 2.0 (the "License");
012 *   you may not use this file except in compliance with the License.
013 *   You may obtain a copy of the License at
014 *
015 *             http://www.apache.org/licenses/LICENSE-2.0
016 *
017 *   Unless required by applicable law or agreed to in writing, software
018 *   distributed under the License is distributed on an "AS IS" BASIS,
019 *   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
020 *   See the License for the specific language governing permissions and
021 *   limitations under the License.
022 * #-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=#
023 *   Artifact    : org.ldp4j.framework:ldp4j-application-api:0.2.2
024 *   Bundle      : ldp4j-application-api-0.2.2.jar
025 * #-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=#
026 */
027package org.ldp4j.application.vocabulary;
028
029import java.io.Serializable;
030
031
032/**
033 * A class for representing a vocabularies. The interface includes facilities
034 * for discovering the terms defined in the vocabulary. methods for retrieving
035 * the representation of the particular term in different formats.
036 *
037 * @version 1.0
038 * @since 1.0.0
039 * @author Miguel Esteban Gutiérrez
040 * @see Term
041 */
042public interface Vocabulary extends Iterable<Term>, Serializable {
043
044  /**
045   * Get the namespace of the vocabulary.
046   *
047   * @return the namespace of the vocabulary. It should never be {@code null}
048   *         nor empty.
049   */
050  String getNamespace();
051
052  /**
053   * Get the preferred prefix for the vocabulary namespace.
054   *
055   * @return the preferred prefix for the namespace. It should never be
056   *         {@code null} nor empty.
057   */
058  String getPreferredPrefix();
059
060  /**
061   * Get the number of terms defined in the vocabulary.
062   *
063   * @return the number of terms defined or {@code 0} if no term is defined.
064   */
065  int size();
066
067  /**
068   * Get the terms defined in the vocabulary.
069   *
070   * @return the terms defined for the vocabulary or an empty array if no
071   *         terms are defined.
072   */
073  Term[] terms();
074
075  /**
076   * Returns the vocabulary term with the specified name. The name must match
077   * exactly an identifier used to declare the term in this vocabulary.
078   *
079   * @param name
080   *            the name of the term to return
081   * @return the term of the vocabulary type with the specified name
082   * @throws IllegalArgumentException
083   *             if {@code name} is null.
084   */
085  Term fromName(String name);
086
087  /**
088   * Returns the vocabulary term specified in a given position.
089   *
090   * @param ordinal
091   *            the position in which the desired term was declared.
092   * @return the term that was declared in the specified position.
093   * @throws IndexOutOfBoundsException
094   *             if the specified ordinal is lower than {@code 0} or greater
095   *             or equal than {@code #size()}.
096   */
097  Term fromOrdinal(int ordinal);
098
099  /**
100   * Returns the vocabulary term that matches the specified value.
101   *
102   * @param <V> the type of value to be processed
103   * @param value
104   *            a value to determine the desired term.
105   * @return the term that upon transformation matches the specified
106   *         {@code value}.
107   * @throws UnsupportedOperationException
108   *             if the terms of the vocabulary cannot be transformed to
109   *             instances a compatible class.
110   * @see Term#as(Class)
111   */
112  <V> Term fromValue(V value);
113
114}