jaroslav@110: /**
jaroslav@110:  * HTML via Java(tm) Language Bindings
jaroslav@110:  * Copyright (C) 2013 Jaroslav Tulach <jaroslav.tulach@apidesign.org>
jaroslav@110:  *
jaroslav@110:  * This program is free software: you can redistribute it and/or modify
jaroslav@110:  * it under the terms of the GNU General Public License as published by
jaroslav@110:  * the Free Software Foundation, version 2 of the License.
jaroslav@110:  *
jaroslav@110:  * This program is distributed in the hope that it will be useful,
jaroslav@110:  * but WITHOUT ANY WARRANTY; without even the implied warranty of
jaroslav@110:  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
jaroslav@110:  * GNU General Public License for more details. apidesign.org
jaroslav@110:  * designates this particular file as subject to the
jaroslav@110:  * "Classpath" exception as provided by apidesign.org
jaroslav@110:  * in the License file that accompanied this code.
jaroslav@110:  *
jaroslav@110:  * You should have received a copy of the GNU General Public License
jaroslav@110:  * along with this program. Look for COPYING file in the top folder.
jaroslav@110:  * If not, see http://wiki.apidesign.org/wiki/GPLwithClassPathException
jaroslav@110:  */
jaroslav@110: package org.apidesign.html.context.spi;
jaroslav@110: 
jaroslav@110: import net.java.html.BrwsrCtx;
jaroslav@110: import org.apidesign.html.context.impl.CtxImpl;
jaroslav@110: 
jaroslav@110: /**
jaroslav@110:  *
jaroslav@110:  * @author Jaroslav Tulach <jaroslav.tulach@apidesign.org>
jaroslav@110:  */
jaroslav@110: public final class Contexts {
jaroslav@110:     private Contexts() {
jaroslav@110:     }
jaroslav@110: 
jaroslav@110:     /** Creates new, empty builder for creation of {@link BrwsrCtx}. At the
jaroslav@110:      * end call the {@link #build()} method to generate the context.
jaroslav@110:      *
jaroslav@110:      * @return new instance of the builder
jaroslav@110:      */
jaroslav@110:     public static Builder newBuilder() {
jaroslav@110:         return new Builder();
jaroslav@110:     }
jaroslav@110: 
jaroslav@110:     /** Seeks for the specified technology in the provided context.
jaroslav@110:      * 
jaroslav@110:      * @param <Tech> type of the technology
jaroslav@110:      * @param context the context to seek in 
jaroslav@110:      *    (previously filled with ({@link Builder#register(java.lang.Class, java.lang.Object, int)})
jaroslav@110:      * @param technology class that identifies the technology
jaroslav@110:      * @return 
jaroslav@110:      */
jaroslav@110:     public static <Tech> Tech find(BrwsrCtx context, Class<Tech> technology) {
jaroslav@110:         return CtxImpl.find(context, technology);
jaroslav@110:     }
jaroslav@110: 
jaroslav@110:     /** Implementors of various HTML technologies should
jaroslav@110:      * register their implementation via {@link ServiceProvider} so
jaroslav@110:      * {@link ServiceProvider} can find them, when their JARs are included
jaroslav@110:      * on the classpath of the running application.
jaroslav@110:      *
jaroslav@110:      * @author Jaroslav Tulach <jaroslav.tulach@apidesign.org>
jaroslav@110:      */
jaroslav@110:     public static interface Provider {
jaroslav@110: 
jaroslav@110:         /** Register into the context if suitable technology is
jaroslav@110:          * available for the requesting class.
jaroslav@110:          * The provider should check if its own technology is available in current
jaroslav@110:          * scope (e.g. proper JDK, proper browser, etc.). The provider
jaroslav@110:          * can also find the right context depending on requestor's classloader, etc.
jaroslav@110:          * <p>
jaroslav@110:          * Providers should use {@link Builder} to enrich appropriately
jaroslav@110:          * the context.
jaroslav@110:          *
jaroslav@110:          * @param context the context builder to fill with technologies
jaroslav@110:          * @param requestor the application class requesting access the the HTML page
jaroslav@110:          * @see BrwsrCtx#findDefault(java.lang.Class)
jaroslav@110:          */
jaroslav@110:         void fillContext(Builder context, Class<?> requestor);
jaroslav@110:     }
jaroslav@110: 
jaroslav@110:     /** Support for providers of new {@link BrwsrCtx}. Providers of different
jaroslav@110:      * technologies should be of particular interest in this class. End users
jaroslav@110:      * designing their application with existing technologies should rather
jaroslav@110:      * point their attention to {@link BrwsrCtx} and co.
jaroslav@110:      *
jaroslav@110:      * @author Jaroslav Tulach <jtulach@netbeans.org>
jaroslav@110:      */
jaroslav@110:     public static final class Builder {
jaroslav@110:         private CtxImpl impl = new CtxImpl();
jaroslav@110: 
jaroslav@110:         Builder() {
jaroslav@110:         }
jaroslav@110:         
jaroslav@110:         /** Registers new technology into the context. Each technology is
jaroslav@110:          * exactly identified by its implementation class and can be associated
jaroslav@110:          * with (positive) priority. In case of presence of multiple technologies
jaroslav@110:          * with the same class, the one with higher lower priority takes precedence.
jaroslav@110:          */
jaroslav@110:         public <Tech> Builder register(Class<Tech> type, Tech impl, int priority) {
jaroslav@110:             if (priority <= 0) {
jaroslav@110:                 throw new IllegalStateException();
jaroslav@110:             }
jaroslav@110:             this.impl.register(type, impl, priority);
jaroslav@110:             return this;
jaroslav@110:         }
jaroslav@110: 
jaroslav@110:         /** Generates context based on values previously inserted into
jaroslav@110:          * this builder.
jaroslav@110:          *
jaroslav@110:          * @return new, immutable instance of {@link BrwsrCtx}
jaroslav@110:          */
jaroslav@110:         public BrwsrCtx build() {
jaroslav@110:             return impl.build();
jaroslav@110:         }
jaroslav@110:     }
jaroslav@110: }