com.yahoo.jdisc.application.BindingMatch Maven / Gradle / Ivy

// Copyright 2017 Yahoo Holdings. Licensed under the terms of the Apache 2.0 license. See LICENSE in the project root.
package com.yahoo.jdisc.application;

import java.net.URI;
import java.util.Objects;

/**
 * This class holds the result of a {@link BindingSet#match(URI)} operation. It contains methods to inspect the
 * groups captured during matching, where a group is defined as a sequence of characters matches by a wildcard
 * in the {@link UriPattern}, and to retrieve the matched target.
 *
 * @param  The class of the target.
 */
public class BindingMatch {

    private final UriPattern.Match match;
    private final T target;
    private final UriPattern matched;

    /**
     * Constructs a new instance of this class.
     *
     * @param match  The match information for this instance.
     * @param target The target of this match.
     * @param matched The matched URI pattern
     * @throws NullPointerException If any argument is null.
     */
    public BindingMatch(UriPattern.Match match, T target, UriPattern matched) {
        Objects.requireNonNull(match, "match");
        Objects.requireNonNull(target, "target");
        this.match = match;
        this.target = target;
        this.matched = matched;
    }

    /**
     * Returns the number of captured groups of this match. Any non-negative integer smaller than the value returned
     * by this method is a valid group index for this match.
     *
     * @return The number of captured groups.
     */
    public int groupCount() {
        return match.groupCount();
    }

    /**
     * Returns the input subsequence captured by the given group by this match. Groups are indexed from left to
     * right, starting at zero. Note that some groups may match an empty string, in which case this method returns the
     * empty string. This method never returns null.
     *
     * @param idx The index of the group to return.
     * @return The (possibly empty) substring captured by the group during matching, never null.
     * @throws IndexOutOfBoundsException If there is no group in the match with the given index.
     */
    public String group(int idx) {
        return match.group(idx);
    }

    /**
     * Returns the matched target.
     *
     * @return The matched target.
     */
    public T target() {
        return target;
    }

    /**
     * Returns the URI pattern that was matched.
     *
     * @return The matched pattern.
     */
    public UriPattern matched() {
        return matched;
    }

}