001/* 002 * Licensed to the Apache Software Foundation (ASF) under one 003 * or more contributor license agreements. See the NOTICE file 004 * distributed with this work for additional information 005 * regarding copyright ownership. The ASF licenses this file 006 * to you under the Apache License, Version 2.0 (the 007 * "License"); you may not use this file except in compliance 008 * with the License. You may obtain a copy of the License at 009 * 010 * http://www.apache.org/licenses/LICENSE-2.0 011 * 012 * Unless required by applicable law or agreed to in writing, 013 * software distributed under the License is distributed on an 014 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY 015 * KIND, either express or implied. See the License for the 016 * specific language governing permissions and limitations 017 * under the License. 018 */ 019package org.apache.reef.tang; 020 021import org.apache.reef.tang.exceptions.BindException; 022import org.apache.reef.tang.implementation.TangImpl; 023 024import java.net.URL; 025 026/** 027 * The root factory interface for Tang. This interface allows callers to 028 * instantiate Tang's core API, and is responsible for memoization and other 029 * runtime optimizations. 030 */ 031public interface Tang { 032 033 /** 034 * Returns an Injector for the given Configurations. 035 * 036 * @param confs a configuration 037 * @return an injector 038 * @throws BindException If the confs conflict, a BindException will be thrown. 039 */ 040 Injector newInjector(final Configuration... confs) 041 throws BindException; 042 043 /** 044 * Returns an Injector for the given Configuration. 045 * 046 * @param confs a configuration 047 * @return an injector 048 */ 049 Injector newInjector(final Configuration confs); 050 051 /** 052 * Returns an Injector based on an empty Configuration. 053 054 * @return an injector 055 */ 056 Injector newInjector(); 057 058 /** 059 * Return a new ConfigurationBuilder that is backed by the provided 060 * ClassHierarchy object. 061 * 062 * @param ch Any valid Tang ClassHierarchy, including ones derived from non-Java application binaries. 063 * @return an instance of ConfigurationBuilder. In Tang's default implementation this returns an instance 064 * or JavaConfigurationBuilder if ch is backed by a Java classloader. 065 */ 066 ConfigurationBuilder newConfigurationBuilder(ClassHierarchy ch); 067 068 /** 069 * Create a new ConfigurationBuilder that is backed by the default 070 * classloader and the provided jars. Following standard Java's semantics, 071 * when looking up a class, Tang will consult the default classloader first, 072 * then the first classpath entry / jar passed to this method, then the 073 * second, and so on. 074 * 075 * @param jars the locations of jar files 076 * @return a new JavaConfigurationBuilder 077 */ 078 JavaConfigurationBuilder newConfigurationBuilder(URL... jars); 079 080 /** 081 * Merge a set of configurations into a new JavaConfiurationBuilder. If 082 * the configurations conflict, this method will throw a bind exception. 083 * <p> 084 * The underlying ClassHierarchies and parameter parsers of the 085 * configurations will be checked for consistency. The returned 086 * configuration builder will be backed by a ClassHierachy that incorporates 087 * the classpath and parsers from all of the provided Configurations. 088 * 089 * @param confs configurations 090 * @return a new ConfigurationBuilder 091 * @throws BindException if any of the configurations contain duplicated or 092 * conflicting bindings, or if the backing ClassHierarchy objects conflict 093 * in some way. 094 */ 095 JavaConfigurationBuilder newConfigurationBuilder(Configuration... confs) 096 throws BindException; 097 098 /** 099 * Create an empty JavaConfigurationBuilder that is capable of parsing 100 * application-specific configuration values. The returned 101 * JavaConfigurationBuilder will be backed by the default classloader. 102 * 103 * @param parameterParsers the parsers for parameters 104 * @return a new ConfigurationBuilder 105 * @throws BindException if any of the configurations contain duplicated or 106 * conflicting bindings, or if the backing ClassHierarchy objects conflict 107 * in some way. 108 */ 109 JavaConfigurationBuilder newConfigurationBuilder( 110 @SuppressWarnings("unchecked") Class<? extends ExternalConstructor<?>>... parameterParsers) 111 throws BindException; 112 113 /** 114 * Create a new JavaConfiguration builder that has additional jars, 115 * incorporates existing configuration data and / or can parse 116 * application-specific types. 117 * 118 * See the documentation for the other newConfigurationBuilder methods in 119 * this class for detailed information about each of the parameters to 120 * this method. 121 * 122 * @param jars the locations of jar files 123 * @param confs configurations 124 * @param parameterParsers the parsers for parameters 125 * @return a configuration builder 126 */ 127 JavaConfigurationBuilder newConfigurationBuilder(URL[] jars, 128 Configuration[] confs, 129 Class<? extends ExternalConstructor<?>>[] parameterParsers) 130 throws BindException; 131 132 /** 133 * Create a new empty ConfigurationBuilder that is backed by the default 134 * classloader. 135 * 136 * @return a configuration builder 137 */ 138 JavaConfigurationBuilder newConfigurationBuilder(); 139 140 /** 141 * @return an instance of JavaClassHierarchy that is backed by the default 142 * Java classloader. ClassHierarchy objects are immutable, so multiple 143 * invocations of this method may return the same instance. 144 */ 145 JavaClassHierarchy getDefaultClassHierarchy(); 146 147 /** 148 * Get a default class hierarchy. 149 * 150 * @param jars the locations of jar files 151 * @param parsers the parsers 152 * @return a custom instance of JavaClassHierarchy. ClassHierarchy objects 153 * are immutable, so multiple invocations of this method may return the 154 * same instance. 155 * TODO Is the class hierarchy returned here backed by the default 156 * classloader or not? If not, then callers will need to merge it with 157 * getDefaultClassHierarchy(). If so, we should add a new method like 158 * getNonDefaultClassHiearchy() that takes the same options as this one. 159 */ 160 JavaClassHierarchy getDefaultClassHierarchy(URL[] jars, Class<? extends ExternalConstructor<?>>[] parsers); 161 162 /** 163 * A factory that returns the default implementation of the Tang interface. 164 */ 165 final class Factory { 166 /** 167 * Return an instance of the default implementation of Tang. 168 * 169 * @return an instance of Tang. 170 */ 171 public static Tang getTang() { 172 return new TangImpl(); 173 } 174 175 /** 176 * Empty private constructor to prohibit instantiation of utility class. 177 */ 178 private Factory() { 179 } 180 } 181 182}