...
This internal model of hierarchical folders was done intentionally in the design of uPortal so that it could potentially be used with whatever structure was desired that could map into this underlying, flexible model. Hence code placed within org.jasig.portal.layout.dlm.DistributedLayoutManager's processLayoutparameters() method must accomodate this underlying model often making code much more complex than it otherwise would be if structural transformation concepts could be taken into consideration. Furthermore, such custom changes usually don't make sense to contributed back to the uPortal baseline code and hence will have to be added back in and recompiled each time that the portal is upgraded to the latest
version of the uPortal code.
Parameter Processing Pipe
Starting in uPortal 2.6 a configuration based, pluggable mechanism is available in DLM allowing an institution to plug in handlers that can act on query and post parameters included in an HTTP request. These handlers can also take part in altering the SAX event stream that represents the user's layout including adding, removing, or altering layout elements without affecting their canonical structure within the DistributedLayoutManager. This pluggable handler support is provided via what is known as the Parameter Processing Pipe. Conceptually, the location of the pipe is shown in the image below.
The uPortal user interface is generated by the class org.jasig.portal.UserInstance. As part of that processing UserInstance delegates to the plugged-in LayoutManager for processing layout parameters. Then it again delegates to have the layout pushed through UserInstance's rendering mechanism as a stream of SAX events. This event stream is what drives the structure and theme transformation. Both interactions pass through the Parameter Processing Pipe. Although shown in the image as being between UserInstance and DistributedLayoutManager the pipe is actually internal
to DistributedLayoutManager and is delegated to by the processLayoutParameters() and getUserLayout() methods.
Processor Interfaces
Plugging a handler in is accomplished by implementing at least one of two new interfaces as shown in the next figure. IParameterProcessor implementations can take part in the processLayoutParameters() call. ISaxProcessor implementations can take part in modifications to the SAX event stream. If a processor implements both interfaces then it can take part in both actions. Both processor types can be plugged-in as part of a set of fixed processors. This means that they are always there and always take part in every invocation of these calls.
Alternatively, processors can be included in a Map of optional processors with each processor being registered with a key that is unique among all registered optional processors. A single optional processor can be installed into the pipe and take part in both of these invocations until another HTTP request selects a different optional processor or removes the current optional processor. Alternatively, if an optional processor implements the IOptionalProcessor
interface then it can cause itself to be removed from being the currently selected optional processor when it has completed its processLayoutParameter tasks.
Optional Processor Selection
An optional processor is selected in an HTTP request by specifying a query or posted parameter of uP_dlmPrc=someKey. The key specified should match one of the registered optional processors. When such a parameter is seen the Parameter Processing Pipe installs that optional processor prior to handling the processLayoutParameters request. At the end of processing layout parameters
by delegating to processors the Pipe checks to see if the current optional processor implements the IOptionalProcessor interface. If it does and the processor indicates by the single method of that interface that it is finished then it is removed from being the currently
selected optional processor. Such a check is made each time that processLayoutParameters() is called.
If that processor does not implement the IOptionalProcessor interface then it will remain as the currently selected optional processor until another HTTP request includes another uP_dlmPrc
parameter. If the value of that parameter is an empty String then the optional processor is removed. If it contains another key then the new processor becomes the optional processor. However, it should be noted that these processor instances are not garbage collected. They remain cached in memory until the next time that processor is needed.
Plugging in Processors
The Parameter Processing Pipe is configured by modifying the properties/dlmContext.xml file. This file has the following structure. In the default configuration two fixed processors are included. Both processors, the ThemeParamInjector and RegularViewChannelRemover implement IParameterProcessor. The former acquires the user's name via IPeron's getFullName() method and injects it into the theme stylesheet as the userName parameter. The latter handes the requests that result when the delete button is pressed on a channel when viewing the portal in regular non-layout-editing mode.
...
The value of the singleton attribute must be specified with care. A Parameter Processing Pipe is instantiated for each user and remains for the duration of that user's session. The specified set of processors are also instantiated. If a processor is thread safe meaning it does not contain any user specific information stored in instance variables then a single instance of that processor could be used in all pipes for all users. To do so the singleton attribute should be set
to true. If the processor is not thread safe and maintains user or state information then its singleton attribute should contain a value of false.
Sample Processors
There are two sample processors included with the Parameter Processing Pipe implementation code that can be plugged in to portray the flexibility and power had by processors. These sample processors are found in the following two classes.
...