org.sandev.basics.util
Interface UIFormAdaptor

public interface UIFormAdaptor

Renders/reconstructs a UIFormContext to/from a user interface. Implementations of UIFormAdaptor adapt specific user interface technologies to standard application processing, while providing for override customization. Implementations provide default rendering capabilities, which can then be customized via

1. transformation templates applied during the rendering process.
2. extension of the adaptor class itself.

UIFormAdaptor implementations can be used by any UI framework.

Most implementations will initialize and re-use a singleton processing class to reduce memory overhead. To support this, implementing classes must:

• provide a no-args constructor
• implement their methods to be fully re-entrant (all necessary context provided in the method arguments, with the exception of global flags set during initialization).

The UIFormAdaptor is intended to be technology neutral, and although intermediate display code representations such as HTML map clearly, the intention is to map to GUI displays, and even non-visual interfaces, with the same application logic. Since forms in most interface technologies can be converted to a parameter Map (the essential job of a UIRenderInput object), and most display technologies follow a setup/write-contents/close rendering paradigm, the UIFormAdaptor interface can adapt most UI technologies. Not all implementations will support all variants of UIRenderOutput although they must support at least one. The UIFormAdaptor provides input reconstruction through getFormContext and output rendering via the dump* methods.

conventions:

Specific field tags (such as enumint, decimalize, flags, metatype, ref, range etc) may define their own rendering conventions. In the absence of specific overriding guidelines, a UIFormAdaptor implementation should follow these general conventions:

• Plain integer (int, long) numeric types are typically displayed in their native toString form for a simple adaptor implementation. A more sophisticated general implementation will take into account locale, and an adaptor tuned for a specific application may also take into account units and/or metatype information. An application may choose to handle units and metatype translations via template transforms, or via extension of the UIFormAdaptor, whichever is easier.
• Simple rendering/reconstruction of a Date display typically follows the default java.text.DateFormat conversions. More sophisticated implementations may utilize locale information, user preferances, screen constraints, calendars and other intelligent controls.
• Strings are generally understood to be plain text, which may be preprocessed during rendering to convert things like email addresses and URLs into links. Longer string values that span multiple display lines, should have their formatting preserved at the level of paragraph breaks and hard line breaks.
• Report messages (messages that are dynamically generated and used primarily for display purposes) can have extensive formatted text components marked as metatype XHTML. A UIFormAdaptor implementation is expected to handle at least the rudimentary XHTML text formatting tags that allow for emphasis, indentation etc. in the displayed text. An implementation that supports SAND UI is also expected to translate any URL of the form

  http://thisapp/ScreenName?myParam=myVal

  into a clickable link leading to the corresponding screen display. The "http://" character sequence signals the need for a link, the the "thisapp" character sequence signals the need for a translation into the UI framework link processing, regardless of the display technology being adapted. The ScreenName is a defined Screen instance in the SandUI. The "scr" parameter name is reserved for post-translation use by the SAND UI processing.

Field Summary

static java.lang.String

SANDUILINK_REGEXP An regular expression which can be used to match SAND UI links in report text.

Method Summary

boolean	allowEditReadOnly() Returns false unless immutable SAND message fields should be displayed as editable.
void	dumpFormOutput(UIRenderOutput uiro, java.lang.String formName, UIFormContext uifc, UIFormAdaptorCallback callback, AuthUser user, AuthFilter filter) Translate the given UIFormContext into a display, via the given UIRenderOutput.
void	dumpPageFooter(UIRenderOutput uiro, java.lang.String closure) If the form display must be terminated with closing output, then this method dumps that output.
void	dumpPageHeader(UIRenderOutput uiro, java.lang.String title, UIFormOwner owner, java.lang.Object context) If the form display must be preceded by setup output, then this method dumps that output.
boolean[]	getActionSupportMap() Returns the current actionSupportMap
boolean[]	getDefaultActionSupportMap() Returns a default actionSupportMap
UIFormContext	getFormContext(UIRenderInput uiri, java.lang.String formName, UIFormContext uifc, UIFormAdaptorCallback callback) Given a map of our current parameter names and values, reconstruct the UIFormContext and return it.
java.lang.String	getHiddenFieldValue() When a field is accessible, but it's value in a particular instance is not, then something must still be displayed.
InstanceClassEnumerator	getInstanceClassEnumerator() Return an InstanceClassEnumerator for the UIFormManager or other caller to use.
UIRenderInput	getUIRenderInput() Return a UIRenderInput instance appropriate for this adaptor.
UIRenderOutputDirect	getUIRenderOutputDirect() Return a UIRenderOutputDirect instance appropriate for this adaptor.
UIRenderOutputStream	getUIRenderOutputStream() Return a UIRenderOutputStream instance appropriate for this adaptor.
UIRenderOutputString	getUIRenderOutputString() Return a UIRenderOutput instance appropriate for this adaptor, where the result can be accessed as a String.
SandInstanceMessage	newInstanceMessage(java.lang.String classtype) Given the short class name of a SandInstanceMessage, return a new object instance of that class.
void	setActionSupportMap(boolean[] actionFlags) Sets the array of boolean flags describing which top level actions are supported.
void	setAllowEditReadOnly(boolean val) Sets the value returned by the allowEditReadOnly method.
void	setHiddenFieldValue(java.lang.String val) Sets the value to be returned by getHiddenFieldValue.

Field Detail

SANDUILINK_REGEXP

static final java.lang.String SANDUILINK_REGEXP

An regular expression which can be used to match SAND UI links in report text. This can be compiled by java.util.regex.Pattern for use in matching links in text.

groups:

• The first group is the screen name, which matches any word characters. So this will terminate on reaching a "?", quote or whitespace. regexp: \w+
• The second group is the parameter string, which is optional. If it does exist, it starts with a '?' separator, followed by words interspersed with '&' and '=' symbols. Because we are doing XML, the '&' may be represented as "&" instead, so we need to pick up on ';' also. regexp: (\?[\w\&\;\=])+

See Also:

Constant Field Values

Method Detail

getUIRenderInput

UIRenderInput getUIRenderInput()

Return a UIRenderInput instance appropriate for this adaptor.

getUIRenderOutputDirect

UIRenderOutputDirect getUIRenderOutputDirect()

Return a UIRenderOutputDirect instance appropriate for this adaptor. If this adaptor uses streams rather than direct output, then this method returns null.

getUIRenderOutputStream

UIRenderOutputStream getUIRenderOutputStream()

Return a UIRenderOutputStream instance appropriate for this adaptor. If this adaptor does not support stream output, then this method returns null.

getUIRenderOutputString

UIRenderOutputString getUIRenderOutputString()

Return a UIRenderOutput instance appropriate for this adaptor, where the result can be accessed as a String. For adaptors where the result is itself text (which will be parsed to produce a display) this provides an opportunity to manipulate what will be displayed before it is actually rendered. Not all adaptors will necessarily support this possibility, those that don't will return null.

getFormContext

UIFormContext getFormContext(UIRenderInput uiri,
                             java.lang.String formName,
                             UIFormContext uifc,
                             UIFormAdaptorCallback callback)
                             throws UIFormAdaptorException

Given a map of our current parameter names and values, reconstruct the UIFormContext and return it. The formName is used to identify which form to load. It must match the name used to dump the form, but may be null in both cases if only one form is being displayed.

If not null, the given form context is used as the working space into which the display values are loaded, so the values in it function as defaults. If null, a new UIFormContext is allocated.

Throws:

UIFormAdaptorException

dumpFormOutput

void dumpFormOutput(UIRenderOutput uiro,
                    java.lang.String formName,
                    UIFormContext uifc,
                    UIFormAdaptorCallback callback,
                    AuthUser user,
                    AuthFilter filter)
                    throws UIFormAdaptorException

Translate the given UIFormContext into a display, via the given UIRenderOutput.

A display will access referenced objects to provide for reasonable linkage descriptions using the instance field values. To do this, it must have access to instance lookup utils.

An adaptor may remove action buttons and/or filter the display of fields and values to avoid presenting scenarios that will be rejected in authorization processing. To do this, the adaptor requires a user and an AuthFilter. If either of these is null or otherwise invalid, then the adaptor will not be able to provide this filtering capability.

Note that it is up to the caller to deal with class level authorization hiding. When the adaptor is called with a given class, it doesn't have much choice except to render a form for it. The adaptor can filter at the field/value/button level only.

Throws:

UIFormAdaptorException

dumpPageHeader

void dumpPageHeader(UIRenderOutput uiro,
                    java.lang.String title,
                    UIFormOwner owner,
                    java.lang.Object context)
                    throws UIFormAdaptorException

If the form display must be preceded by setup output, then this method dumps that output. Typical examples include header information, layout information etc. If no setup is required then this method does nothing.

The owner is provided to allow for callback processing. The context provides additional information for the callback to use, depending on the interface implementation.

Throws:

UIFormAdaptorException

dumpPageFooter

void dumpPageFooter(UIRenderOutput uiro,
                    java.lang.String closure)
                    throws UIFormAdaptorException

If the form display must be terminated with closing output, then this method dumps that output. Typical examples include footer information, layout closure etc. If no closeout is required then this method does nothing.

Throws:

UIFormAdaptorException

setActionSupportMap

void setActionSupportMap(boolean[] actionFlags)
                         throws UIFormAdaptorException

Sets the array of boolean flags describing which top level actions are supported. If this method is not called then the default support map is used.

An action is enabled if:

1. it is enabled in the actionSupportMap
2. it is relevant based on the UIFormContext modePath
3. the user is authorized to perform the action

During processing, the UIFormContext is first initialized with a copy of this actionSupportMap. Then actions which are not relevant to the current mode, or which the user is not authorized for, are disabled.

Note that this mapping array is for top level actions only. Field-level actions (add/delete or find/remove) are determined solely based on the context and user authorization.

Throws:

UIFormAdaptorException

getActionSupportMap

boolean[] getActionSupportMap()

Returns the current actionSupportMap

getDefaultActionSupportMap

boolean[] getDefaultActionSupportMap()

Returns a default actionSupportMap

getHiddenFieldValue

java.lang.String getHiddenFieldValue()

When a field is accessible, but it's value in a particular instance is not, then something must still be displayed. This method returns the value to use.

setHiddenFieldValue

void setHiddenFieldValue(java.lang.String val)

Sets the value to be returned by getHiddenFieldValue. If this is not set explicitely, a default value such as "-" or "N/A" will typically be used.

allowEditReadOnly

boolean allowEditReadOnly()

Returns false unless immutable SAND message fields should be displayed as editable. Fields like uniqueID are usually read-only, but may need to be hand edited in some cases (such as specifying initial data for a deployment configuration). If no value has been explicitely set using setAllowEditReadOnly, then this method returns false.

This mechanism is intentionally separate from displaying fields as read-only based on authorization. If a user is not authorized to view or edit a message field, then it is up to the UI to filter the resulting display.

setAllowEditReadOnly

void setAllowEditReadOnly(boolean val)

Sets the value returned by the allowEditReadOnly method.

newInstanceMessage

SandInstanceMessage newInstanceMessage(java.lang.String classtype)
                                       throws UIFormAdaptorException

Given the short class name of a SandInstanceMessage, return a new object instance of that class.

Throws:

UIFormAdaptorException

getInstanceClassEnumerator

InstanceClassEnumerator getInstanceClassEnumerator()

Return an InstanceClassEnumerator for the UIFormManager or other caller to use.