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.NameResolutionException;
022import org.apache.reef.tang.types.ClassNode;
023import org.apache.reef.tang.types.Node;
024
025/**
026 * ClassHierarchy objects store information about the interfaces
027 * and implementations that are available in a particular runtime
028 * environment.
029 * <p>
030 * When Tang is running inside the same environment as the injected
031 * objects, ClassHierarchy is simply a read-only representation of
032 * information that is made available via language reflection.
033 * <p>
034 * If Tang is set up to perform remote injection, then the ClassHierarchy
035 * it runs against is backed by a flat file, or other summary of the
036 * libraries that will be available during injection.
037 */
038public interface ClassHierarchy {
039  /**
040   * Lookup a node in this class hierarchy.
041   *
042   * @param fullName The full name of the class that will be looked up.
043   * @return A non-null reference to a ClassNode or a NamedParameterNode.
044   * @throws NameResolutionException If the class is not found.
045   * @throws org.apache.reef.tang.exceptions.ClassHierarchyException If the class does not pass Tang's static analysis.
046   */
047  Node getNode(String fullName) throws NameResolutionException;
048
049  /**
050   * Return whether the impl is a subclass of inter.
051   *
052   * @param inter a interface class
053   * @param impl a implementation class
054   * @return true if impl is a subclass of inter.
055   */
056  boolean isImplementation(ClassNode<?> inter, ClassNode<?> impl);
057
058  /**
059   * Merge the contents of this ClassHierarchy and the provided one into a new
060   * class hierarchy.  This allows reflection information from multiple jars to
061   * be incorporated into a single ClassHierarchy object.  Typical applications
062   * do not call this method, and instead provide classpath (or C# assembly)
063   * information to Tang when they create ConfigurationBuilder and Configuration
064   * objects.  The Configuration API transparently invokes merge as necessary,
065   * allowing applications to combine configurations that were built against
066   * differing classpaths.
067   * <p>
068   * ClassHierarchies derived from applications written in different languages
069   * cannot be merged.
070   *
071   * @param ch a class hierarchy to be merged
072   * @return the merged class hierarchy
073   */
074  ClassHierarchy merge(ClassHierarchy ch);
075
076  /**
077   * Return a reference to the root of the ClassHierarchy.  This is needed by
078   * serialization routines (which have to iterate over the ClassHierarchy's
079   * state).  Unfortunately, due to limitations of Java, JavaClassHierarchy
080   * objects need to be built lazily as callers request classes by name.
081   * There is no way to provide an interface that enumerates known claases
082   * without exposing this fact; therefore, the Node returned by this method
083   * can change over time.
084   * <p>
085   * Normal callers (all use cases except ClassHierarchy serialization)
086   * should use getNode(String) to lookup classes, since getNamespace() can
087   * not support lazy loading of unknown classes.
088   *
089   * @return a reference to the root node of this ClassHierarchy.
090   */
091  Node getNamespace();
092
093}