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}