diff -r 30f20d9c0986 -r bdc3d696dd4a context/src/main/java/org/netbeans/html/context/spi/Contexts.java --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/context/src/main/java/org/netbeans/html/context/spi/Contexts.java Tue Aug 26 18:13:30 2014 +0200 @@ -0,0 +1,192 @@ +/** + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER. + * + * Copyright 2013-2014 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-2014 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.netbeans.html.context.spi; + +import java.util.ServiceLoader; +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 + */ +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 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 null + */ + public static Tech find(BrwsrCtx context, Class technology) { + return CtxImpl.find(context, technology); + } + + /** Seeks {@link ServiceLoader} for all registered instances of + * {@link Provider} and asks them to {@link Provider#fillContext(org.netbeans.html.context.spi.Contexts.Builder, java.lang.Class) fill + * the builder}. + * + * @param requestor the application class for which to find the context + * @param cb the context builder to register technologies into + * @return true, if some instances of the provider were + * found, false otherwise + * @since 0.7.6 + */ + public static boolean fillInByProviders(Class requestor, Contexts.Builder cb) { + boolean found = false; + ClassLoader l; + try { + l = requestor.getClassLoader(); + } catch (SecurityException ex) { + l = null; + } + for (Provider cp : ServiceLoader.load(Provider.class, l)) { + cp.fillContext(cb, requestor); + found = true; + } + try { + for (Provider cp : ServiceLoader.load(Provider.class, Provider.class.getClassLoader())) { + cp.fillContext(cb, requestor); + found = true; + } + } catch (SecurityException ex) { + if (!found) { + throw ex; + } + } + if (!found) { + for (Provider cp : ServiceLoader.load(Provider.class)) { + cp.fillContext(cb, requestor); + found = true; + } + } + return found; + } + + /** Implementors of various HTML technologies should + * register their implementation via org.openide.util.lookup.ServiceProvider, so + * {@link ServiceLoader} can find them, when their JARs are included + * on the classpath of the running application. + * + * @author Jaroslav Tulach + */ + 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. + *

+ * 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 + */ + 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 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 Builder register(Class type, Tech impl, int position) { + if (impl == null) { + return this; + } + 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(); + } + } +}