MarkupSource.java

/**
 * 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.brixcms.markup;

import org.brixcms.markup.tag.Item;

/**
 * Source for Node Page markup. The MarkupSources can be nested, with the innermost MarkupSource providing the base
 * markup (e.g. parsing an XML/HTML data) and the wrapper MarkupSources doing transformations on it.
 *
 * @author Matej Knopp
 */
public interface MarkupSource {
    /**
     * Returns the Doctype string of the document or null if there is no doctype present.
     *
     * @return
     */
    public String getDoctype();

    /**
     * Returns expiration token for the markup. The token will be remembered alongside the markup items and will be used
     * to determine whether the generated markup is not yet expired (by being passed as argument to the {@link
     * #isMarkupExpired(Object)} method.
     * <p/>
     * This method is called when generating the markup before the first invocation of {@link #nextMarkupItem()}
     *
     * @return expiration token
     */
    public Object getExpirationToken();

    /**
     * Determines if the markup generated with the given expiration token is already expired or still valid.
     *
     * @param expirationToken token generated by {@link #getExpirationToken()} before generating actual markup
     * @return <code>true</code> if the markup is already expired, <code>false</code> if it is still valid.
     */
    public boolean isMarkupExpired(Object expirationToken);

    /**
     * Returns next markup item. If there is no markup item left returns <code>null</code>.
     *
     * @return next markup item or <code>null</code>
     */
    public Item nextMarkupItem();
}