/**

 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.

 *

 * Copyright 2013-2013 Oracle and/or its affiliates. All rights reserved.

 *

 * Oracle and Java are registered trademarks of Oracle and/or its affiliates.

 * Other names may be trademarks of their respective owners.

 *

 * The contents of this file are subject to the terms of either the GNU

 * General Public License Version 2 only ("GPL") or the Common

 * Development and Distribution License("CDDL") (collectively, the

 * "License"). You may not use this file except in compliance with the

 * License. You can obtain a copy of the License at

 * http://www.netbeans.org/cddl-gplv2.html

 * or nbbuild/licenses/CDDL-GPL-2-CP. See the License for the

 * specific language governing permissions and limitations under the

 * License.  When distributing the software, include this License Header

 * Notice in each file and include the License file at

 * nbbuild/licenses/CDDL-GPL-2-CP.  Oracle designates this

 * particular file as subject to the "Classpath" exception as provided

 * by Oracle in the GPL Version 2 section of the License file that

 * accompanied this code. If applicable, add the following below the

 * License Header, with the fields enclosed by brackets [] replaced by

 * your own identifying information:

 * "Portions Copyrighted [year] [name of copyright owner]"

 *

 * Contributor(s):

 *

 * The Original Software is NetBeans. The Initial Developer of the Original

 * Software is Oracle. Portions Copyright 2013-2013 Oracle. All Rights Reserved.

 *

 * If you wish your version of this file to be governed by only the CDDL

 * or only the GPL Version 2, indicate your decision by adding

 * "[Contributor] elects to include this software in this distribution

 * under the [CDDL or GPL Version 2] license." If you do not indicate a

 * single choice of license, a recipient has the option to distribute

 * your version of this file under either the CDDL, the GPL Version 2 or

 * to extend the choice of license to its licensees as provided above.

 * However, if you add GPL Version 2 code and therefore, elected the GPL

 * Version 2 license, then the option applies only if the new code is

 * made subject to such option by the copyright holder.

 */

package org.apidesign.html.context.spi;

import net.java.html.BrwsrCtx;

import org.netbeans.html.context.impl.CtxImpl;

/** Factory class to assign various technologies 

 * to a {@link BrwsrCtx browser context}. Start with {@link #newBuilder()}

 * and then assign technologies with {@link Builder#register(java.lang.Class, java.lang.Object, int)}

 * method.

 *

 * @author Jaroslav Tulach <jaroslav.tulach@apidesign.org>

 */

public final class Contexts {

    private Contexts() {

    }

    /** Creates new, empty builder for creation of {@link BrwsrCtx}. At the

     * end call the {@link Builder#build()} method to generate the context.

     *

     * @return new instance of the builder

     */

    public static Builder newBuilder() {

        return new Builder();

    }

    /** Seeks for the specified technology in the provided context.

     * 

     * @param <Tech> type of the technology

     * @param context the context to seek in 

     *    (previously filled with ({@link Builder#register(java.lang.Class, java.lang.Object, int)})

     * @param technology class that identifies the technology

     * @return the technology in the context or <code>null</code>

     */

    public static <Tech> Tech find(BrwsrCtx context, Class<Tech> technology) {

        return CtxImpl.find(context, technology);

    }

    /** Implementors of various HTML technologies should

     * register their implementation via {@link java.util.ServiceProvider} so

     * {@link java.util.ServiceProvider} can find them, when their JARs are included

     * on the classpath of the running application.

     *

     * @author Jaroslav Tulach <jaroslav.tulach@apidesign.org>

     */

    public static interface Provider {

        /** Register into the context if suitable technology is

         * available for the requesting class.

         * The provider should check if its own technology is available in current

         * scope (e.g. proper JDK, proper browser, etc.). The provider

         * can also find the right context depending on requestor's classloader, etc.

         * <p>

         * Providers should use {@link Builder} to enrich appropriately

         * the context.

         *

         * @param context the context builder to fill with technologies

         * @param requestor the application class requesting access the the HTML page

         * @see BrwsrCtx#findDefault(java.lang.Class)

         */

        void fillContext(Builder context, Class<?> requestor);

    }

    /** Support for providers of new {@link BrwsrCtx}. Providers of different

     * technologies should be of particular interest in this class. End users

     * designing their application with existing technologies should rather

     * point their attention to {@link BrwsrCtx} and co.

     *

     * @author Jaroslav Tulach <jtulach@netbeans.org>

     */

    public static final class Builder {

        private final CtxImpl impl = new CtxImpl();

        Builder() {

        }

        /** Registers new technology into the context. Each technology is

         * exactly identified by its implementation class and can be associated

         * with (positive) priority. In case of presence of multiple technologies

         * with the same class, the one with higher lower priority takes precedence.

         * @param <Tech> type of technology to register

         * @param type the real class of the technology type

         * @param impl an instance of the technology class

         * @param position the lower position, the more important implementation 

         *    which will be consulted sooner when seeking for a {@link Contexts#find(net.java.html.BrwsrCtx, java.lang.Class)}

         *    an implementation

         * @return this builder

         */

        public <Tech> Builder register(Class<Tech> type, Tech impl, int position) {

            if (position <= 0) {

                throw new IllegalStateException();

            }

            this.impl.register(type, impl, position);

            return this;

        }

        /** Generates context based on values previously inserted into

         * this builder.

         *

         * @return new, immutable instance of {@link BrwsrCtx}

         */

        public BrwsrCtx build() {

            return impl.build();

        }

    }

}