Source code

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
021
022import org.apache.reef.tang.annotations.Name;
023import org.apache.reef.tang.exceptions.BindException;
024
025import java.util.List;
026import java.util.Set;
027
028/**
029 * Convenience methods that extend the ConfigurationBuilder but assume that
030 * the underlying ClassHierarchy delegates to the default Java classloader.
031 * <p>
032 * In addition to being less verbose, this interface expresses many of Tang's
033 * type checks in Java's generic type system.  This improves IDE
034 * auto-completion.  It also allows the errors to be caught at compile time
035 * instead of later on in the build process, or at runtime.
036 *
037 * @see org.apache.reef.tang.formats.ConfigurationModule which pushes additional type checks to class load
038 * time.  This allows Tint, Tang's static analysis tool, to detect a wide
039 * range of runtime configuration errors at build time.
040 */
041public interface JavaConfigurationBuilder extends ConfigurationBuilder {
042
043  /**
044   * Bind named parameters, implementations or external constructors, depending
045   * on the types of the classes passed in.
046   *
047   * @param <T> a type
048   * @param iface an interface class
049   * @param impl an implementation class
050   * @return the configuration builder
051   */
052  <T> JavaConfigurationBuilder bind(Class<T> iface, Class<?> impl) throws BindException;
053
054  /**
055   * Binds the Class impl as the implementation of the interface iface.
056   *
057   * @param <T> a type
058   * @param iface an interface class
059   * @param impl an implementation class
060   * @return the configuration builder
061   */
062  <T> JavaConfigurationBuilder bindImplementation(Class<T> iface, Class<? extends T> impl)
063      throws BindException;
064
065
066  /**
067   * Set the value of a named parameter.
068   *
069   * @param name  The dummy class that serves as the name of this parameter.
070   * @param value A string representing the value of the parameter. Reef must know
071   *              how to parse the parameter's type.
072   * @return the configuration builder
073   * @throws org.apache.reef.tang.exceptions.NameResolutionException which occurs when name resolution fails
074   */
075  JavaConfigurationBuilder bindNamedParameter(Class<? extends Name<?>> name, String value)
076      throws BindException;
077
078  <T> JavaConfigurationBuilder bindNamedParameter(Class<? extends Name<T>> iface,
079                                                  Class<? extends T> impl) throws BindException;
080
081  <T> JavaConfigurationBuilder bindConstructor(Class<T> c,
082                                               Class<? extends ExternalConstructor<? extends T>> v)
083      throws BindException;
084
085  <T> JavaConfigurationBuilder bindSetEntry(Class<? extends Name<Set<T>>> iface, String value) throws BindException;
086
087  <T> JavaConfigurationBuilder bindSetEntry(Class<? extends Name<Set<T>>> iface, Class<? extends T> impl)
088      throws BindException;
089
090  /**
091   * Binds a specific list to a named parameter. List's elements can be string values or class implementations.
092   * Their type would be checked in this method. If their types are not applicable to the named parameter,
093   * it will make an exception.
094   *
095   * @param iface The target named parameter to be injected into
096   * @param impl  A concrete list
097   * @param <T> A type
098   * @return the configuration builder
099   * @throws BindException It occurs when iface is not a named parameter or impl is not compatible to bind
100   */
101  <T> JavaConfigurationBuilder bindList(Class<? extends Name<List<T>>> iface, List impl)
102      throws BindException;
103}