fr.ght1pc9kc.juery.basic.QueryStringParser Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of juery-basic Show documentation
There is a newer version: 1.4.2
package fr.ght1pc9kc.juery.basic;

import fr.ght1pc9kc.juery.api.Criteria;
import fr.ght1pc9kc.juery.api.PageRequest;
import fr.ght1pc9kc.juery.api.pagination.Sort;
import fr.ght1pc9kc.juery.basic.parser.QueryStringParserImpl;

import java.util.List;
import java.util.Map;

/**
 * Allow parsing and formatting a querystring
 *
 * The provided implementation of {@link QueryStringParser} allow two ways to specify page to be returned :
 * 
 *     by offset, with {@code from} and {@code to}
 *     by page, with {@code page} and {@code size}
 * 
 * This two ways are exclusive, so you can't use both, {@code page} and {@code from}, in the querystring.
 * In the querystring, if {@code page} and {@code from} parameters are present, the page is resolved by page.
 * The {@code from} parameter is ignored.
 * This is true only for the provided implementation.
 */
public interface QueryStringParser {

    /**
     * Format a {@link PageRequest} into an URL querystring.
     *
     * Ex:
     * {@code
     *   PageRequest.of(
     *           Pagination.of(2, 100, Sort.of(new Order(Direction.ASC, "name"), new Order(Direction.DESC, "email"))),
     *           Criteria.property("profile").eq("jedi").and(Criteria.property("job").eq("master")))),
     * }
     * will result in {@code `_p=2&_s=name,-email&profile=jedi&job=master`}
     *
     * @param pr The {@link PageRequest} to format
     * @return The string representing a valid QueryString
     */
    String format(PageRequest pr);

    /**
     * Format a {@link Sort} into a sort querystring parameter
     *
     * Ex:
     * {@code
     *   Sort.of(new Order(Direction.ASC, "name"), new Order(Direction.DESC, "email")))
     * }
     * will result in {@code `_s=name,-email`}
     *
     * @param sort The {@link Sort} to format
     * @return The string representing a valid sort parameter for querystring
     */
    String formatSortValue(Sort sort);

    /**
     * Parse divided querystring into {@link PageRequest}.
     *
     * @param queryString The separated querystring parameters as {@code Map>}
     * @return The PageRequest
     */
    PageRequest parse(Map> queryString);

    /**
     * Parse a URL querystring into {@link PageRequest}.
     *
     * @param queryString The querystring to parse
     * @return The PageRequest
     */
    PageRequest parse(String queryString);

    /**
     * Parse querystring parameter into a {@link Criteria}.
     *
     * @param key        The querystring to parse
     * @param paramValue The value of the parameter. Can be a List if the same parameter as multiple values.
     * @return The {@link Criteria}
     */
    Criteria parseCriterionParameter(String key, List paramValue);

    /**
     * Build a parser with specific {@link ParserConfiguration}.
     * This allow to customize the querystring parameters name for pagination and sorting
     *
     * @param config The configuration
     * @return The {@link QueryStringParser} using the specified configuration
     */
    static QueryStringParser withConfig(ParserConfiguration config) {
        return new QueryStringParserImpl(config);
    }

    /**
     * Build a parser with default configuration: {@link ParserConfiguration#DEFAULT}
     * This allow to customize the querystring parameters name for pagination and sorting
     *
     * @return The {@link QueryStringParser} using the default configuration
     * @see ParserConfiguration#DEFAULT
     */
    static QueryStringParser withDefaultConfig() {
        return new QueryStringParserImpl(ParserConfiguration.DEFAULT);
    }
}