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}