01: // Copyright 2006 The Apache Software Foundation
02: //
03: // Licensed under the Apache License, Version 2.0 (the "License");
04: // you may not use this file except in compliance with the License.
05: // You may obtain a copy of the License at
06: //
07: // http://www.apache.org/licenses/LICENSE-2.0
08: //
09: // Unless required by applicable law or agreed to in writing, software
10: // distributed under the License is distributed on an "AS IS" BASIS,
11: // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12: // See the License for the specific language governing permissions and
13: // limitations under the License.
14:
15: package org.apache.tapestry.services;
16:
17: /**
18: * Provides access to environment services, which are almost always provided to enclosed components
19: * by enclosing components.
20: * <p>
21: * The Environment acts like a collection of stacks. Each stack contains environmental service
22: * providers of a given type.
23: */
24: public interface Environment {
25: /**
26: * @param <T>
27: * the type of environmental service
28: * @param type
29: * class used to select a service
30: * @return the current service of that type, or null if no service of that type has been added
31: */
32: <T> T peek(Class<T> type);
33:
34: /**
35: * @param <T>
36: * the type of environmental service
37: * @param type
38: * class used to select a service
39: * @return the current service
40: * @throws RuntimeException
41: * if no service of that type has been added
42: */
43: <T> T peekRequired(Class<T> type);
44:
45: /**
46: * Removes and returns the top environmental service of the selected type.
47: *
48: * @param <T>
49: * @param type
50: * @return
51: * @throws NoSuchElementException
52: * if the environmental stack (for the specified type) is empty
53: */
54: <T> T pop(Class<T> type);
55:
56: /**
57: * Pushes a new service onto the stack. The old service at the top of the stack is returned (it
58: * may be null).
59: *
60: * @param <T>
61: * @param type
62: * the type of service to store
63: * @param instance
64: * the service instance
65: * @return the previous top service
66: */
67: <T> T push(Class<T> type, T instance);
68:
69: /**
70: * Clears all stacks; used when initializing the Environment before a render.
71: */
72: void clear();
73: }
|