1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/context/src/main/java/org/apidesign/html/context/spi/Contexts.java Tue May 28 13:31:42 2013 +0200
1.3 @@ -0,0 +1,115 @@
1.4 +/**
1.5 + * HTML via Java(tm) Language Bindings
1.6 + * Copyright (C) 2013 Jaroslav Tulach <jaroslav.tulach@apidesign.org>
1.7 + *
1.8 + * This program is free software: you can redistribute it and/or modify
1.9 + * it under the terms of the GNU General Public License as published by
1.10 + * the Free Software Foundation, version 2 of the License.
1.11 + *
1.12 + * This program is distributed in the hope that it will be useful,
1.13 + * but WITHOUT ANY WARRANTY; without even the implied warranty of
1.14 + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
1.15 + * GNU General Public License for more details. apidesign.org
1.16 + * designates this particular file as subject to the
1.17 + * "Classpath" exception as provided by apidesign.org
1.18 + * in the License file that accompanied this code.
1.19 + *
1.20 + * You should have received a copy of the GNU General Public License
1.21 + * along with this program. Look for COPYING file in the top folder.
1.22 + * If not, see http://wiki.apidesign.org/wiki/GPLwithClassPathException
1.23 + */
1.24 +package org.apidesign.html.context.spi;
1.25 +
1.26 +import net.java.html.BrwsrCtx;
1.27 +import org.apidesign.html.context.impl.CtxImpl;
1.28 +
1.29 +/**
1.30 + *
1.31 + * @author Jaroslav Tulach <jaroslav.tulach@apidesign.org>
1.32 + */
1.33 +public final class Contexts {
1.34 + private Contexts() {
1.35 + }
1.36 +
1.37 + /** Creates new, empty builder for creation of {@link BrwsrCtx}. At the
1.38 + * end call the {@link #build()} method to generate the context.
1.39 + *
1.40 + * @return new instance of the builder
1.41 + */
1.42 + public static Builder newBuilder() {
1.43 + return new Builder();
1.44 + }
1.45 +
1.46 + /** Seeks for the specified technology in the provided context.
1.47 + *
1.48 + * @param <Tech> type of the technology
1.49 + * @param context the context to seek in
1.50 + * (previously filled with ({@link Builder#register(java.lang.Class, java.lang.Object, int)})
1.51 + * @param technology class that identifies the technology
1.52 + * @return
1.53 + */
1.54 + public static <Tech> Tech find(BrwsrCtx context, Class<Tech> technology) {
1.55 + return CtxImpl.find(context, technology);
1.56 + }
1.57 +
1.58 + /** Implementors of various HTML technologies should
1.59 + * register their implementation via {@link ServiceProvider} so
1.60 + * {@link ServiceProvider} can find them, when their JARs are included
1.61 + * on the classpath of the running application.
1.62 + *
1.63 + * @author Jaroslav Tulach <jaroslav.tulach@apidesign.org>
1.64 + */
1.65 + public static interface Provider {
1.66 +
1.67 + /** Register into the context if suitable technology is
1.68 + * available for the requesting class.
1.69 + * The provider should check if its own technology is available in current
1.70 + * scope (e.g. proper JDK, proper browser, etc.). The provider
1.71 + * can also find the right context depending on requestor's classloader, etc.
1.72 + * <p>
1.73 + * Providers should use {@link Builder} to enrich appropriately
1.74 + * the context.
1.75 + *
1.76 + * @param context the context builder to fill with technologies
1.77 + * @param requestor the application class requesting access the the HTML page
1.78 + * @see BrwsrCtx#findDefault(java.lang.Class)
1.79 + */
1.80 + void fillContext(Builder context, Class<?> requestor);
1.81 + }
1.82 +
1.83 + /** Support for providers of new {@link BrwsrCtx}. Providers of different
1.84 + * technologies should be of particular interest in this class. End users
1.85 + * designing their application with existing technologies should rather
1.86 + * point their attention to {@link BrwsrCtx} and co.
1.87 + *
1.88 + * @author Jaroslav Tulach <jtulach@netbeans.org>
1.89 + */
1.90 + public static final class Builder {
1.91 + private CtxImpl impl = new CtxImpl();
1.92 +
1.93 + Builder() {
1.94 + }
1.95 +
1.96 + /** Registers new technology into the context. Each technology is
1.97 + * exactly identified by its implementation class and can be associated
1.98 + * with (positive) priority. In case of presence of multiple technologies
1.99 + * with the same class, the one with higher lower priority takes precedence.
1.100 + */
1.101 + public <Tech> Builder register(Class<Tech> type, Tech impl, int priority) {
1.102 + if (priority <= 0) {
1.103 + throw new IllegalStateException();
1.104 + }
1.105 + this.impl.register(type, impl, priority);
1.106 + return this;
1.107 + }
1.108 +
1.109 + /** Generates context based on values previously inserted into
1.110 + * this builder.
1.111 + *
1.112 + * @return new, immutable instance of {@link BrwsrCtx}
1.113 + */
1.114 + public BrwsrCtx build() {
1.115 + return impl.build();
1.116 + }
1.117 + }
1.118 +}