org.attoparser.select.IMarkupSelectorReferenceResolver Maven / Gradle / Ivy

Go to download

Show more of this group Show more artifacts with this name
Show all versions of attoparser Show documentation

Powerful, fast and easy to use HTML and XML parser for Java

There is a newer version: 2.0.7.RELEASE

/*
 * =============================================================================
 *
 *   Copyright (c) 2012-2014, The ATTOPARSER team (http://www.attoparser.org)
 *
 *   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 org.attoparser.select;

/**
 * 
 *   Interface modeling reference resolvers, the objects that can be used for tuning the selector matching
 *   operations done by {@link org.attoparser.select.BlockSelectorMarkupHandler} and
 *   {@link org.attoparser.select.NodeSelectorMarkupHandler}.
 * 
 * 
 *   This tuning is performed by means of selector references, which look like
 *   %ref and which are passed to the reference resolvers in order to convert them to more specific selectors.
 * 
 * 
 *   For example, a reference resolver might convert %someref to //p[data-additional="someref"] so
 *   that %someref simply becomes an easier way to specify "a paragraph element that has an attribute
 *   called 'data-additional' with value 'someref'".
 * 
 * 
 *   As another example, this %fragment (or simply fragment) syntax is heavily used by
 *   Thymeleaf
 *   in order to search for elements with a th:fragment or data-th-fragment attribute with a
 *   specific "fragment" value.
 * 
 * 
 *   Note: avoid creating new instances of the same class implementing this interface: better always use just one
 *   instance, unless the implementation gives non-deterministic results. The object equality of this class
 *   (its equals()) will be used for caching parsed selectors.
 * 
 *
 * @author Daniel Fernández
 *
 * @since 2.0.0
 *
 */
public interface IMarkupSelectorReferenceResolver {

    /**
     * 
     *   Convert the specified value, coming from a selector reference, into a complete markup
     *   selector.
     * 
     * 
     *   For example given a selector reference like %someref, this method will be called with reference
     *   value "someref", and the result could be something like //p[data-additional="someref"] in
     *   order to make %ref a synonym to "a paragraph element that has an attribute
     *   called 'data-additional' with value 'someref'".
     * 
     *
     * @param reference the reference value (without the %).
     * @return the equivalent, complete markup selector.
     */
    public String resolveSelectorFromReference(final String reference);

}