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 ClassHierarchyException If the class does not pass Tang's static analysis.
046   */
047  Node getNode(String fullName) throws NameResolutionException;
048
049  /**
050   * @return true if impl is a subclass of inter.
051   */
052  boolean isImplementation(ClassNode<?> inter, ClassNode<?> impl);
053
054  /**
055   * Merge the contents of this ClassHierarchy and the provided one into a new
056   * class hierarchy.  This allows reflection information from multiple jars to
057   * be incorporated into a single ClassHierarchy object.  Typical applications
058   * do not call this method, and instead provide classpath (or C# assembly)
059   * information to Tang when they create ConfigurationBuilder and Configuration
060   * objects.  The Configuration API transparently invokes merge as necessary,
061   * allowing applications to combine configurations that were built against
062   * differing classpaths.
063   * <p/>
064   * ClassHierarchies derived from applications written in different languages
065   * cannot be merged.
066   */
067  ClassHierarchy merge(ClassHierarchy ch);
068
069  /**
070   * Return a reference to the root of the ClassHierarchy.  This is needed by
071   * serialization routines (which have to iterate over the ClassHierarchy's
072   * state).  Unfortunately, due to limitations of Java, JavaClassHierarchy
073   * objects need to be built lazily as callers request classes by name.
074   * There is no way to provide an interface that enumerates known claases
075   * without exposing this fact; therefore, the Node returned by this method
076   * can change over time.
077   * <p/>
078   * Normal callers (all use cases except ClassHierarchy serialization)
079   * should use getNode(String) to lookup classes, since getNamespace() can
080   * not support lazy loading of unknown classes.
081   *
082   * @return a reference to the root node of this ClassHierarchy.
083   */
084  Node getNamespace();
085
086}