001/*
002 * Licensed to the Apache Software Foundation (ASF) under one or more
003 * contributor license agreements.  See the NOTICE file distributed with
004 * this work for additional information regarding copyright ownership.
005 * The ASF licenses this file to You under the Apache License, Version 2.0
006 * (the "License"); you may not use this file except in compliance with
007 * the License.  You may obtain a copy of the License at
008 *
009 *      http://www.apache.org/licenses/LICENSE-2.0
010 *
011 * Unless required by applicable law or agreed to in writing, software
012 * distributed under the License is distributed on an "AS IS" BASIS,
013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014 * See the License for the specific language governing permissions and
015 * limitations under the License.
016 */
017package org.apache.wicket.markup.head;
018
019import java.io.Closeable;
020
021import org.apache.wicket.request.Response;
022
023/**
024 * Interface that is used to render header elements (usually javascript and CSS references).
025 * 
026 * Implementation of this interface is responsible for filtering duplicate contributions (so that
027 * for example the same javascript is not loaded twice) during the same request.
028 * 
029 * @author Matej Knopp
030 */
031public interface IHeaderResponse extends Closeable
032{
033        /**
034         * Renders the given {@link HeaderItem} to the response if none of its
035         * {@linkplain HeaderItem#getRenderTokens() tokens} has been rendered before.
036         * <p>
037         * Automatically marks all item's tokens as rendered.
038         * 
039         * @param item
040         *            The item to render.
041         * @see #markRendered(Object)
042         */
043        void render(HeaderItem item);
044
045        /**
046         * Marks the given object as rendered. The object can be anything (string, resource reference,
047         * etc...). The purpose of this function is to allow user to manually keep track of rendered
048         * items. This can be useful for items that are expensive to generate (like interpolated text).
049         * 
050         * @param object
051         *            object to be marked as rendered.
052         */
053        void markRendered(Object object);
054
055        /**
056         * Returns whether the given object has been marked as rendered.
057         * 
058         * @param object
059         *            Object that is queried to be rendered
060         * @return Whether the object has been marked as rendered during the request
061         * 
062         * @see #markRendered(Object)
063         */
064        boolean wasRendered(Object object);
065
066        /**
067         * Returns the response that can be used to write arbitrary text to the head section.
068         * <p>
069         * Note: This method is kind of dangerous as users are able to write to the output whatever they
070         * like.
071         * 
072         * @return Response
073         */
074        Response getResponse();
075
076        /**
077         * Mark Header rendering is completed and subsequent usage will be ignored. If some kind of
078         * buffering is used internally, this action will mark that the contents has to be flushed out.
079         */
080        @Override
081        void close();
082
083        /**
084         * @return if header rendering is completed and subsequent usage will be ignored
085         */
086        boolean isClosed();
087}