View Javadoc
1   /*
2    * Copyright (c) 2001, 2012, Oracle and/or its affiliates. All rights reserved.
3    * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4    *
5    * This code is free software; you can redistribute it and/or modify it
6    * under the terms of the GNU General Public License version 2 only, as
7    * published by the Free Software Foundation.  Oracle designates this
8    * particular file as subject to the "Classpath" exception as provided
9    * by Oracle in the LICENSE file that accompanied this code.
10   *
11   * This code is distributed in the hope that it will be useful, but WITHOUT
12   * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13   * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
14   * version 2 for more details (a copy is included in the LICENSE file that
15   * accompanied this code).
16   *
17   * You should have received a copy of the GNU General Public License version
18   * 2 along with this work; if not, write to the Free Software Foundation,
19   * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20   *
21   * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22   * or visit www.oracle.com if you need additional information or have any
23   * questions.
24   */
25  
26  package com.sun.tools.javac.util;
27  
28  import java.util.*;
29  
30  /**
31   * Support for an abstract context, modelled loosely after ThreadLocal
32   * but using a user-provided context instead of the current thread.
33   *
34   * <p>Within the compiler, a single Context is used for each
35   * invocation of the compiler.  The context is then used to ensure a
36   * single copy of each compiler phase exists per compiler invocation.
37   *
38   * <p>The context can be used to assist in extending the compiler by
39   * extending its components.  To do that, the extended component must
40   * be registered before the base component.  We break initialization
41   * cycles by (1) registering a factory for the component rather than
42   * the component itself, and (2) a convention for a pattern of usage
43   * in which each base component registers itself by calling an
44   * instance method that is overridden in extended components.  A base
45   * phase supporting extension would look something like this:
46   *
47   * <p><pre>{@code
48   * public class Phase {
49   *     protected static final Context.Key<Phase> phaseKey =
50   *         new Context.Key<Phase>();
51   *
52   *     public static Phase instance(Context context) {
53   *         Phase instance = context.get(phaseKey);
54   *         if (instance == null)
55   *             // the phase has not been overridden
56   *             instance = new Phase(context);
57   *         return instance;
58   *     }
59   *
60   *     protected Phase(Context context) {
61   *         context.put(phaseKey, this);
62   *         // other intitialization follows...
63   *     }
64   * }
65   * }</pre>
66   *
67   * <p>In the compiler, we simply use Phase.instance(context) to get
68   * the reference to the phase.  But in extensions of the compiler, we
69   * must register extensions of the phases to replace the base phase,
70   * and this must be done before any reference to the phase is accessed
71   * using Phase.instance().  An extended phase might be declared thus:
72   *
73   * <p><pre>{@code
74   * public class NewPhase extends Phase {
75   *     protected NewPhase(Context context) {
76   *         super(context);
77   *     }
78   *     public static void preRegister(final Context context) {
79   *         context.put(phaseKey, new Context.Factory<Phase>() {
80   *             public Phase make() {
81   *                 return new NewPhase(context);
82   *             }
83   *         });
84   *     }
85   * }
86   * }</pre>
87   *
88   * <p>And is registered early in the extended compiler like this
89   *
90   * <p><pre>
91   *     NewPhase.preRegister(context);
92   * </pre>
93   *
94   *  <p><b>This is NOT part of any supported API.
95   *  If you write code that depends on this, you do so at your own risk.
96   *  This code and its internal interfaces are subject to change or
97   *  deletion without notice.</b>
98   */
99  public class Context {
100     /** The client creates an instance of this class for each key.
101      */
102     public static class Key<T> {
103         // note: we inherit identity equality from Object.
104     }
105 
106     /**
107      * The client can register a factory for lazy creation of the
108      * instance.
109      */
110     public static interface Factory<T> {
111         T make(Context c);
112     };
113 
114     /**
115      * The underlying map storing the data.
116      * We maintain the invariant that this table contains only
117      * mappings of the form
118      * {@literal Key<T> -> T }
119      * or
120      * {@literal Key<T> -> Factory<T> }
121      */
122     private Map<Key<?>,Object> ht = new HashMap<Key<?>,Object>();
123 
124     /** Set the factory for the key in this context. */
125     public <T> void put(Key<T> key, Factory<T> fac) {
126         checkState(ht);
127         Object old = ht.put(key, fac);
128         if (old != null)
129             throw new AssertionError("duplicate context value");
130         checkState(ft);
131         ft.put(key, fac); // cannot be duplicate if unique in ht
132     }
133 
134     /** Set the value for the key in this context. */
135     public <T> void put(Key<T> key, T data) {
136         if (data instanceof Factory<?>)
137             throw new AssertionError("T extends Context.Factory");
138         checkState(ht);
139         Object old = ht.put(key, data);
140         if (old != null && !(old instanceof Factory<?>) && old != data && data != null)
141             throw new AssertionError("duplicate context value");
142     }
143 
144     /** Get the value for the key in this context. */
145     public <T> T get(Key<T> key) {
146         checkState(ht);
147         Object o = ht.get(key);
148         if (o instanceof Factory<?>) {
149             Factory<?> fac = (Factory<?>)o;
150             o = fac.make(this);
151             if (o instanceof Factory<?>)
152                 throw new AssertionError("T extends Context.Factory");
153             Assert.check(ht.get(key) == o);
154         }
155 
156         /* The following cast can't fail unless there was
157          * cheating elsewhere, because of the invariant on ht.
158          * Since we found a key of type Key<T>, the value must
159          * be of type T.
160          */
161         return Context.<T>uncheckedCast(o);
162     }
163 
164     public Context() {}
165 
166     /**
167      * The table of preregistered factories.
168      */
169     private Map<Key<?>,Factory<?>> ft = new HashMap<Key<?>,Factory<?>>();
170 
171     public Context(Context prev) {
172         kt.putAll(prev.kt);     // retain all implicit keys
173         ft.putAll(prev.ft);     // retain all factory objects
174         ht.putAll(prev.ft);     // init main table with factories
175     }
176 
177     /*
178      * The key table, providing a unique Key<T> for each Class<T>.
179      */
180     private Map<Class<?>, Key<?>> kt = new HashMap<Class<?>, Key<?>>();
181 
182     private <T> Key<T> key(Class<T> clss) {
183         checkState(kt);
184         Key<T> k = uncheckedCast(kt.get(clss));
185         if (k == null) {
186             k = new Key<T>();
187             kt.put(clss, k);
188         }
189         return k;
190     }
191 
192     public <T> T get(Class<T> clazz) {
193         return get(key(clazz));
194     }
195 
196     public <T> void put(Class<T> clazz, T data) {
197         put(key(clazz), data);
198     }
199     public <T> void put(Class<T> clazz, Factory<T> fac) {
200         put(key(clazz), fac);
201     }
202 
203     /**
204      * TODO: This method should be removed and Context should be made type safe.
205      * This can be accomplished by using class literals as type tokens.
206      */
207     @SuppressWarnings("unchecked")
208     private static <T> T uncheckedCast(Object o) {
209         return (T)o;
210     }
211 
212     public void dump() {
213         for (Object value : ht.values())
214             System.err.println(value == null ? null : value.getClass());
215     }
216 
217     public void clear() {
218         ht = null;
219         kt = null;
220         ft = null;
221     }
222 
223     private static void checkState(Map<?,?> t) {
224         if (t == null)
225             throw new IllegalStateException();
226     }
227 }