org.apache.tapestry5.services
Interface Environment

All Known Implementing Classes:

EnvironmentImpl

public interface Environment

Provides access to environment objects, which are almost always provided to enclosed components by enclosing components. Environmental services are a form of very late binding.

The Environment acts like a collection of stacks. Each stack contains environmental objects of a given type. Most often, a stack has zero or one elements, but on occasion, a particular component will push an override onto the stack for the benefit of the components it encloses.

See Also:

Environmental, EnvironmentalShadowBuilder

Method Summary

void	clear() Clears all stacks; used when initializing the Environment before a render.
<T> EnvironmentalAccess<T>	getAccess(Class<T> type) For some type, returns a temporary access object for the type.
<T> T	peek(Class<T> type) Peeks at the current top of the indicated stack.
<T> T	peekRequired(Class<T> type) Peeks at the current top of the indicated stack (which must have a non-null value).
<T> T	pop(Class<T> type) Removes and returns the top environmental object of the selected type.
<T> T	push(Class<T> type, T instance) Pushes a new service onto the stack.

Method Detail

peek

<T> T peek(Class<T> type)

Peeks at the current top of the indicated stack.

Type Parameters:

T - the type of environmental object

Parameters:

type - class used to select the object

Returns:

the current object of that type, or null if no service of that type has been added

peekRequired

<T> T peekRequired(Class<T> type)

Peeks at the current top of the indicated stack (which must have a non-null value).

Type Parameters:

T - the type of environmental object

Parameters:

type - class used to select the object

Returns:

the current object of the specified type

Throws:

RuntimeException - if no service of that type has been added

pop

<T> T pop(Class<T> type)

Removes and returns the top environmental object of the selected type.

Type Parameters:

T - the type of environmental object

Parameters:

type - class used to select the object

Returns:

the object just removed

Throws:

NoSuchElementException - if the environmental stack (for the specified type) is empty

push

<T> T push(Class<T> type,
           T instance)

Pushes a new service onto the stack. The old service at the top of the stack is returned (it may be null).

Type Parameters:

T - the type of environmental object

Parameters:

type - class used to select the object

instance - the service object

Returns:

the previous top service

clear

void clear()

Clears all stacks; used when initializing the Environment before a render.

getAccess

<T> EnvironmentalAccess<T> getAccess(Class<T> type)

For some type, returns a temporary access object for the type. The access object is efficient because it ties directly to the thread's instance of the Environment service, it also caches the current value.

The access object must be discarded at the end of the request (it will be unusable at that point anyway).

Type Parameters:

T -

Parameters:

type - type of environmental object

Returns:

access object that can be used to see the current environmental object of the type

Since:

5.0.19