Package org.kohsuke.stapler

Class Facet

java.lang.Object

org.kohsuke.stapler.Facet

Direct Known Subclasses:

StaticViewFacet

public abstract class Facet
extends Object

Aspect of stapler that brings in an optional language binding. Put MetaInfServices on subtypes so that Stapler can discover them.

Author:

Kohsuke Kawaguchi

Field Summary

Fields

Modifier and Type	Field	Description
static boolean	ALLOW_VIEW_NAME_PATH_TRAVERSAL
static final Logger	LOGGER

Constructor Summary

Constructors

Constructor	Description
Facet()

Method Summary

Modifier and Type	Method	Description
void	buildFallbackDispatchers(MetaClass owner, List<Dispatcher> dispatchers)	Adds Dispatchers that do catch-all behaviours like "doDispatch" does.
void	buildIndexDispatchers(MetaClass owner, List<Dispatcher> dispatchers)	Adds Dispatchers that serves the likes of index.EXT The default implementation invokes handleIndexRequest(RequestImpl, ResponseImpl, Object, MetaClass) but facet implementations can improve runtime dispatch performance by testing the presence of index view page upfront.
abstract void	buildViewDispatchers(MetaClass owner, List<Dispatcher> dispatchers)	Adds Dispatchers that look at one token and binds that to the views associated with the 'it' object.
protected <S> jakarta.servlet.RequestDispatcher	createRequestDispatcher(AbstractTearOff<?,? extends S,?> scriptLoader, ScriptExecutor<? super S> scriptExecutor, Object it, String viewName)	Creates a RequestDispatcher that integrates with DispatchValidator and FilteredDispatchTriggerListener.
jakarta.servlet.RequestDispatcher	createRequestDispatcher(RequestImpl request, Class type, Object it, String viewName)
jakarta.servlet.RequestDispatcher	createRequestDispatcher(RequestImpl request, Klass<?> type, Object it, String viewName)	Creates a RequestDispatcher that handles the given view, or return null if no such view was found.
protected <S> Dispatcher	createValidatingDispatcher(AbstractTearOff<?,? extends S,?> scriptLoader, ScriptExecutor<? super S> scriptExecutor)	Creates a Dispatcher that integrates DispatchValidator with the provided script loader and executor.
static List<Facet>	discover(ClassLoader cl)	Discovers all the facets in the classloader.
static <T> List<T>	discoverExtensions(Class<T> type, ClassLoader... cls)
protected String	getExtensionSuffix()	For Facets that require a particular file extension to be put in any case.
Klass<?>	getKlass(Object o)	Maps an instance to a Klass.
protected <S> boolean	handleIndexRequest(AbstractTearOff<?,? extends S,?> scriptLoader, ScriptExecutor<? super S> scriptExecutor, RequestImpl req, ResponseImpl rsp, Object node)	Handles an index request by dispatching a script.
abstract boolean	handleIndexRequest(RequestImpl req, ResponseImpl rsp, Object node, MetaClass nodeMetaClass)	Attempts to route the HTTP request to the 'index' page of the 'it' object.
protected boolean	isBasename(String potentialPath)	Ensure the path that is passed is only the name of the file and not a path

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Details

LOGGER

public static final Logger LOGGER

ALLOW_VIEW_NAME_PATH_TRAVERSAL

public static boolean ALLOW_VIEW_NAME_PATH_TRAVERSAL

Constructor Details

Facet

public Facet()

Method Details

buildViewDispatchers

public abstract void buildViewDispatchers(MetaClass owner,
 List<Dispatcher> dispatchers)

Adds Dispatchers that look at one token and binds that to the views associated with the 'it' object.

See Also:

• createValidatingDispatcher(AbstractTearOff, ScriptExecutor)

buildIndexDispatchers

public void buildIndexDispatchers(MetaClass owner,
 List<Dispatcher> dispatchers)

Adds Dispatchers that serves the likes of index.EXT The default implementation invokes handleIndexRequest(RequestImpl, ResponseImpl, Object, MetaClass) but facet implementations can improve runtime dispatch performance by testing the presence of index view page upfront.

buildFallbackDispatchers

public void buildFallbackDispatchers(MetaClass owner,
 List<Dispatcher> dispatchers)

Adds Dispatchers that do catch-all behaviours like "doDispatch" does.

discover

public static List<Facet> discover(ClassLoader cl)

Discovers all the facets in the classloader.

discoverExtensions

public static <T> List<T> discoverExtensions(Class<T> type,
 ClassLoader... cls)

createRequestDispatcher

@CheckForNull
public jakarta.servlet.RequestDispatcher createRequestDispatcher(RequestImpl request,
 Klass<?> type,
 Object it,
 String viewName)
                                                          throws IOException

Creates a RequestDispatcher that handles the given view, or return null if no such view was found.

Parameters:

type - If "it" is non-null, it.getClass(). Otherwise the class from which the view is searched.

Throws:

IOException

See Also:

• createRequestDispatcher(AbstractTearOff, ScriptExecutor, Object, String)

createRequestDispatcher

@CheckForNull
public jakarta.servlet.RequestDispatcher createRequestDispatcher(RequestImpl request,
 Class type,
 Object it,
 String viewName)
                                                          throws IOException

Throws:

IOException

handleIndexRequest

public abstract boolean handleIndexRequest(RequestImpl req,
 ResponseImpl rsp,
 Object node,
 MetaClass nodeMetaClass)
                                    throws IOException,
jakarta.servlet.ServletException

Attempts to route the HTTP request to the 'index' page of the 'it' object.

Returns:

true if the processing succeeds. Otherwise false.

Throws:

IOException

jakarta.servlet.ServletException

See Also:

• handleIndexRequest(AbstractTearOff, ScriptExecutor, RequestImpl, ResponseImpl, Object)

getKlass

public Klass<?> getKlass(Object o)

Maps an instance to a Klass. This is the generalization of o.getClass(). This is for those languages that use something other than Class to represent the concept of a class. Those facets that are fine with o.getClass() should return null so that it gives other facets a chance to map it better.

isBasename

protected boolean isBasename(String potentialPath)

Ensure the path that is passed is only the name of the file and not a path

getExtensionSuffix

@NonNull
protected String getExtensionSuffix()

For Facets that require a particular file extension to be put in any case. Just return an empty String if the Facet does not want to have such behavior. If you do want to have an extension added, you must ensure you provide the dot at the first character position, see JellyFacet

createValidatingDispatcher

@NonNull
protected <S> Dispatcher createValidatingDispatcher(@NonNull
 AbstractTearOff<?,? extends S,?> scriptLoader,
 @NonNull
 ScriptExecutor<? super S> scriptExecutor)

Creates a Dispatcher that integrates DispatchValidator with the provided script loader and executor. If an exception or one of its causes is a CancelRequestHandlingException, this will cause the Dispatcher to cancel and return false, thus allowing for further dispatchers to attempt to handle the request. This also requires validation to pass before any output can be written to the response. In any error case, the configured FilteredDispatchTriggerListener will be notified.

Type Parameters:

S - type of script

Parameters:

scriptLoader - tear-off script loader to find views

scriptExecutor - script executor for rendering views

Returns:

dispatcher that handles scripts

Since:

TODO

See Also:

• WebApp.setDispatchValidator(DispatchValidator)
• WebApp.setFilteredDispatchTriggerListener(FilteredDispatchTriggerListener)

handleIndexRequest

protected <S> boolean handleIndexRequest(@NonNull
 AbstractTearOff<?,? extends S,?> scriptLoader,
 @NonNull
 ScriptExecutor<? super S> scriptExecutor,
 @NonNull
 RequestImpl req,
 @NonNull
 ResponseImpl rsp,
 @CheckForNull
 Object node)
                                  throws jakarta.servlet.ServletException,
IOException

Handles an index request by dispatching a script.

Throws:

jakarta.servlet.ServletException

IOException

Since:

TODO

createRequestDispatcher

@CheckForNull
protected <S> jakarta.servlet.RequestDispatcher createRequestDispatcher(@NonNull
 AbstractTearOff<?,? extends S,?> scriptLoader,
 @NonNull
 ScriptExecutor<? super S> scriptExecutor,
 @CheckForNull
 Object it,
 @NonNull
 String viewName)

Creates a RequestDispatcher that integrates with DispatchValidator and FilteredDispatchTriggerListener.

Type Parameters:

S - view type

Parameters:

scriptLoader - tear-off script loader for finding views

scriptExecutor - script executor for rendering views

it - the model node being dispatched against

viewName - name of the view to load and execute

Returns:

a RequestDispatcher that performs similar validation to createValidatingDispatcher(AbstractTearOff, ScriptExecutor)

Since:

TODO

See Also:

• WebApp.setDispatchValidator(DispatchValidator)
• WebApp.setFilteredDispatchTriggerListener(FilteredDispatchTriggerListener)