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.ext;
028
029import java.io.Serializable;
030import java.util.List;
031
032/**
033 * A collection of values defined for a query parameter. The values are defined
034 * as strings, which can be transformed to other Java types.
035 */
036public interface Parameter extends Serializable {
037
038  /**
039   * Returns the name of the parameter.
040   *
041   * @return the name of the parameter
042   */
043  String name();
044
045  /**
046   * Returns {@code true} if this parameter contains multiple values.
047   *
048   * @return {@code true} if this parameter contains multiple values
049   */
050  boolean isMultivalued();
051
052  /**
053   * Returns the number of values in this parameter. If the parameter contains
054   * more than {@code Integer.MAX_VALUE} value, returns
055   * {@code Integer.MAX_VALUE}.
056   *
057   * @return the number of values in this parameter
058   */
059  int cardinality();
060
061  /**
062   * Returns the first raw value of this parameter.
063   *
064   * @return the first raw value of this parameter
065   */
066  String rawValue();
067
068  /**
069   * Returns all the raw values of this parameter. If the parameter is not
070   * multivalued, the result will just contain that parameter's single value.
071   *
072   * @return the raw values of this parameter
073   */
074  List<String> rawValues();
075
076  /**
077   * Returns the first raw value of this parameter as an instance of a given
078   * type.
079   *
080   * @param <T> the type of object to be returned
081   * @param clazz
082   *            the {@code Class} for the type T to which the raw value will
083   *            be transformed to.
084   * @return the instance of the specified {@code Class} to which the first
085   *         raw value of this parameter is transformed to.
086   * @throws ObjectTransformationException
087   *             if the raw value cannot be transformed to the specified type
088   *             T.
089   */
090  <T> T rawValueAs(Class<? extends T> clazz);
091
092  /**
093   * Returns the raw values of this parameter as instances of a given type.
094   *
095   * @param <T> the type of object to be returned
096   * @param clazz
097   *            the {@code Class} for the type T to which the raw values will
098   *            be transformed to.
099   * @return the instances of the specified {@code Class} to which the raw
100   *         values of this parameter are transformed to.
101   * @throws ObjectTransformationException
102   *             if any of the raw values cannot be transformed to the
103   *             specified type T.
104   */
105  <T> List<T> rawValuesAs(Class<? extends T> clazz);
106
107}