net.sourceforge.urin.Query Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of urin Show documentation
Urin is an open source URI generator and parser written in Java.
There is a newer version: 5.2
/*
 * Copyright 2020 Mark Slater
 *
 * Licensed 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 net.sourceforge.urin;

import static net.sourceforge.urin.CharacterSetMembershipFunction.QUERY_AND_FRAGMENT_NON_PERCENT_ENCODED_CHARACTERS;
import static net.sourceforge.urin.PercentEncodingPartial.PercentEncoding.percentEncodingString;

/**
 * A query component of a URI.
 * Immutable and thread safe.
 *
 * @param  The type of value represented by the query - {@code String} in the general case.
 * @see RFC 3986 - Query
 */
public class Query extends PercentEncodingUnaryValue {

    private static final PercentEncodingPartial.PercentEncoding PERCENT_ENCODING = percentEncodingString(new PercentEncoder(QUERY_AND_FRAGMENT_NON_PERCENT_ENCODED_CHARACTERS));

    /**
     * The {@code MakingDecoder} used by standard queries.
     */
    public static final MakingDecoder, String, String> STRING_QUERY_MAKING_DECODER = new MakingDecoder, String, String>(PercentEncodingPartial.noOp()) {
        @Override
        protected Query makeOne(final String value) {
            return query(value);
        }
    };

    private Query(final ENCODES value, final PercentEncodingPartial.PercentEncoding percentEncoding) {
        super(value, percentEncoding);
    }

    /**
     * Constructor for subclasses of {@code Query} with scheme specific percent encoding of characters beyond that specified for generic URI {@code Query}s.
     *
     * @param value                  the (non encoded) value this object represents.
     * @param percentEncodingPartial the {@code PercentEncodingPartial} this subclass will use.
     */
    protected Query(final ENCODES value, final PercentEncodingPartial percentEncodingPartial) {
        this(value, percentEncodingPartial.apply(PERCENT_ENCODING));
    }

    /**
     * Factory method for creating {@code Query}s.
     *
     * @param query any {@code String} to represent as a {@code Query}.
     * @return a {@code Query} representing the given {@code String}.
     */
    public static Query query(final String query) {
        return new Query<>(query, PERCENT_ENCODING);
    }

    /**
     * Factory method for {@code MakingDecoder}s of {@code String} {@code Query}s.
     *
     * @return a {@code MakingDecoder} of {@code String} {@code Query}s.
     * @deprecated use {@link Query#STRING_QUERY_MAKING_DECODER} instead.
     */
    @Deprecated
    public static MakingDecoder, String, String> stringQueryMaker() {
        return STRING_QUERY_MAKING_DECODER;
    }

    static > QUERY parseQuery(final String queryString, final MakingDecoder queryMakingDecoder) throws ParseException {
        return queryMakingDecoder.toMaker(PERCENT_ENCODING).make(queryString);
    }

    /**
     * Gets the (non-encoded) value of this query.
     *
     * @return the (non-encoded) value of this query.
     */
    public final ENCODES value() {
        return value;
    }
}