org.apache.wicket.request.mapper.parameter.INamedParameters.java Source code

Introduction

Here is the source code for org.apache.wicket.request.mapper.parameter.INamedParameters.java

Source

/*
 * Licensed to the Apache Software Foundation (ASF) under one or more
 * contributor license agreements.  See the NOTICE file distributed with
 * this work for additional information regarding copyright ownership.
 * 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.
 */
package org.apache.wicket.request.mapper.parameter;

import java.util.List;
import java.util.Set;

import org.apache.wicket.request.IRequestMapper;
import org.apache.wicket.util.io.IClusterable;
import org.apache.wicket.util.lang.Args;
import org.apache.wicket.util.string.StringValue;

/**
 * Container for parameters that are identified by their name
 * 
 * @author igor
 */
public interface INamedParameters {
    /**
     * A hint where the parameter is read/parsed from.
     */
    enum Type {
        /**
         * The named parameter is set manually in the application code
         */
        MANUAL,

        /**
         * The named parameter is read/parsed from the query string
         */
        QUERY_STRING,

        /**
         * The named parameter is read/parsed from the url path
         */
        PATH
    }

    /**
     * Represents a named parameter entry. There can be multiple {@link NamedPair}s in
     * {@link PageParameters} that have same key.
     * 
     * @author Matej Knopp
     */
    @SuppressWarnings("serial")
    class NamedPair implements IClusterable {
        private final String key;
        private final String value;
        private final Type type;

        /**
         * Creates a named parameter entry that is set manually in the application code.
         * 
         * @param key
         * @param value
         */
        public NamedPair(final String key, final String value) {
            this(key, value, Type.MANUAL);
        }

        /**
         * Creates a named parameter entry
         * 
         * @param key
         * @param value
         * @param type
         */
        public NamedPair(final String key, final String value, Type type) {
            this.key = Args.notEmpty(key, "key");
            this.value = Args.notNull(value, "value");
            this.type = Args.notNull(type, "type");
        }

        /**
         * @return key
         */
        public String getKey() {
            return key;
        }

        /**
         * @return value
         */
        public String getValue() {
            return value;
        }

        /**
         * @return type
         */
        public Type getType() {
            return type;
        }

        @Override
        public boolean equals(Object o) {
            if (this == o)
                return true;
            if (o == null || getClass() != o.getClass())
                return false;

            NamedPair namedPair = (NamedPair) o;

            if (key != null ? !key.equals(namedPair.key) : namedPair.key != null)
                return false;
            if (value != null ? !value.equals(namedPair.value) : namedPair.value != null)
                return false;

            return true;
        }

        @Override
        public int hashCode() {
            int result = key != null ? key.hashCode() : 0;
            result = 31 * result + (value != null ? value.hashCode() : 0);
            return result;
        }
    }

    /**
     * Return set of all named parameter names.
     * 
     * @return named parameter names
     */
    Set<String> getNamedKeys();

    /**
     * Returns parameter value of named parameter with given name
     * 
     * @param name
     * @return parameter value
     */
    StringValue get(final String name);

    /**
     * Return list of all values for named parameter with given name
     * 
     * @param name
     * @return list of parameter values
     */
    List<StringValue> getValues(final String name);

    /**
     * @return All named parameters in exact order.
     */
    List<NamedPair> getAllNamed();

    /**
     * @param type
     *          The type to filter
     * @return All named parameters with the given type. If the type is {@code null} then returns all named parameters.
     */
    List<NamedPair> getAllNamedByType(Type type);

    /**
     * Returns the position of a named parameter.
     * 
     * @param name
     *            the name of the parameter to look for
     * @return the position of the parameter. {@code -1} if there is no parameter with that name.
     */
    int getPosition(String name);

    /**
     * Removes named parameter with given name.
     * 
     * @param name
     *            the name of the parameter to remove
     * @param values
     *            values used as criteria. The parameter will be removed only if its value is equal
     *            to any of the criteria.
     * @return this
     */
    INamedParameters remove(final String name, String... values);

    /**
     * Adds value to named parameter with given name.
     * 
     * @param name
     * @param value
     * @param type
     * @return this
     */
    INamedParameters add(final String name, final Object value, Type type);

    /**
     * Adds named parameter to a specified position. The {@link IRequestMapper}s may or may not take
     * the order into account.
     * 
     * @param name
     * @param value
     * @param index
     * @param type
     * @return this
     */
    INamedParameters add(final String name, final Object value, final int index, Type type);

    /**
     * Sets the named parameter on specified position. The {@link IRequestMapper}s may or may not
     * take the order into account.
     * 
     * @param name
     * @param value
     * @param index
     * @param type
     * @return this
     */
    INamedParameters set(final String name, final Object value, final int index, Type type);

    /**
     * Sets the value for named parameter with given name.
     * 
     * @param name
     * @param value
     * @param type
     * @return this
     */
    INamedParameters set(final String name, final Object value, Type type);

    /**
     * Removes all named parameters.
     * 
     * @return this
     */
    INamedParameters clearNamed();

}