struts-sandbox/overdrive/Nexus/Core/IRequestContext.cs - struts-archive - Git at Google

 /*
  * Copyright 2005 The Apache Software Foundation.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
  * You may obtain a copy of the License at
  *
  *      http://www.apache.org/licenses/LICENSE-2.0
  *
  * Unless required by applicable law or agreed to in writing, software
  * distributed under the License is distributed on an "AS IS" BASIS,
  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
 using System;
 using System.Collections;
 using Agility.Core;
 using Nexus.Core.Profile;
 using Nexus.Core.Tables;

 namespace Nexus.Core
 {
 	/// <summary>
 	/// Exchange data between business and presentation layers [OVR-7].
 	/// </summary>
 	/// <remarks><p>
 	/// An IRequestContext can predefine whatever properties we need for
 	/// storing input, output, messages, and other common attributes,
 	/// including Locale (or Culture) and user credentials.
 	/// </p><p>
 	/// A key member is the FieldTable.
 	/// The FieldTable uses XForms terminology for its members
 	/// and IRequestContext members follow suit.
 	/// For example, "errors" are called "Alerts" and generic
 	/// messages are called "Hints,
 	/// since these are terms used by the FieldTable and XForms.
 	/// </p></remarks>
 	///
 	public interface IRequestContext : IContext
 	{
 		#region Processing

 		/// <summary>
 		/// Identify the top-level Command (or Chain) processing
 		/// this Context.
 		/// </summary>
 		/// <remarks><P>
 		/// The Command property corresponds to ID of INexusCommand
 		/// for the initial Command or Chain.
 		/// </P></remarks>
 		///
 		string Command { get; set; }

 		/// <summary>
 		/// Provide the top-level Command (or Chain) processing this Context.
 		/// </summary>
 		/// <remarks><p>
 		/// Command corresponds to ID of INexusCommand for the
 		/// initial Command or Chain.
 		/// </p></remarks>
 		///
 		IRequestCommand CommandBin { get; set; }


 		/// <summary>
 		/// Provide the FieldTable for this Context.
 		/// </summary>
 		/// <remarks><p>
 		/// The default implementation uses the Catalog to inject the global
 		/// Field Table reference.
 		/// The Context, and members with access to a Context,
 		/// can use the FieldTable to validate and format values,
 		/// and even to create controls that display values.
 		/// </p></remarks>
 		///
 		IFieldTable FieldTable { get; set; }

 		/// <summary>
 		/// User profile, which includes user ID and Locale.
 		/// </summary>
 		IProfile Profile { get; set; }

 		/// <summary>
 		/// Return true if an Outcome object is present.
 		/// </summary>
 		/// <returns>True if an Outcome context is present.</returns>
 		///
 		bool HasOutcome { get; }

 		/// <summary>
 		/// Return a IList stored under the Command ID, if any.
 		/// </summary>
 		/// <remarks><p>
 		/// Some Commands returns List of values.
 		/// So that Commands can work together as part of a Chain,
 		/// list-based Commands are expected to store the
 		/// list under their own Command ID.
 		/// Outcome is a convenience method to access the
 		/// initial or "outermost" Command or Chain ID.
 		/// </p>
 		/// <p>
 		/// To allow use as subcommands in a Chain,
 		/// IRequestCommand implementations should prefer the idiom
 		/// <code>Context[ID] = object</code>
 		/// to using the Outcome directly.
 		/// Since they might not be the initial Command,
 		/// but rather a subcommand, or link, in a Chain.
 		/// </p><p>
 		/// Outcome is more convenient to presentation layer clients,
 		/// who are looking for the top-level output,
 		/// rather than output of a particular subcommand.
 		/// </p><p>
 		/// As mentioned, both Outcome and the context[ID] idiom
 		/// can be used by Command that return lists of values.
 		/// Commands that return a single set of fields
 		/// can store the result directly in the main Context.
 		/// This strategy allows one Command to obtain field values
 		/// to be used by another Command
 		/// (like piping output between Unix shell commands.)
 		/// </p><p>
 		/// Note that "Outcome" is an "alias" to an entry in
 		/// this context.
 		/// Unlike FieldState, Outcome is not a subcontext
 		/// in its own right.
 		/// </p></remarks>
 		///
 		object Outcome { get; set; }

 		/// <summary>
 		/// Indicate whether a Criteria is present.
 		/// </summary>
 		/// <returns>True if a Criteria is present.</returns>
 		bool HasCriteria();

 		/// <summary>
 		/// Provide an optional subcontext containing input or output
 		/// values, usually expressed as display strings.
 		/// </summary>
 		/// <remarks>
 		/// <p>
 		/// Criteria is provided for Commands that accept input
 		/// from other components which may need to be validated,
 		/// converted, or formatted before use.
 		/// If the proposed FieldState is accepted,
 		/// the entries may be merged into the root Context,
 		/// perhaps after type conversion or formatting tasks.
 		/// If the proposed FieldState is not accepted,
 		/// the entries are not merged into the root Context,
 		/// and there should be Errors or a Fault explaining
 		/// why the FieldState (e.g input) cannot be accepted.
 		/// </p>
 		/// <p>
 		/// In practice, it is expected, but not required, that
 		/// all the FieldState entries will contain string values.
 		/// </p>
 		/// <p>
 		/// Commands should only act on the Criteria in order
 		/// to transfer values between the FieldState and the
 		/// root Context.
 		/// Conventional Commands will look to the root Context
 		/// for the state and make any expected changes
 		/// or additions directly to the root context.
 		/// FieldState is not expected to be used by a Commands
 		/// unless input is being submitted from an untrusted or
 		/// naive component, or needs to be transformed for use
 		/// by a display component.
 		/// </p>
 		/// </remarks>
 		IDictionary Criteria { get; set; }

 		#endregion

 		#region Messaging

 		string FormatTemplate(string template, string value);

 		/// <summary>
 		/// Record a list of alert (or error) messages,
 		/// keyed by the field causing the message,
 		/// or to a magic global key.
 		/// </summary>
 		/// <remark><p>
 		/// TODO: Refactor as NameValueCollection ?
 		/// </p></remark>
 		///
 		IDictionary Alerts { get; set; }

 		/// <summary>
 		/// Add an alert message under the "global" key.
 		/// </summary>
 		/// <param name="template">Message template.</param>
 		///
 		void AddAlert(string template);

 		/// <summary>
 		/// Add an alert message, creating the context if needed.
 		/// </summary>
 		/// <remarks>
 		/// Multiple messages can be added for a key and retrieved as a List.
 		/// </remarks>
 		/// <param name="template">Message template.</param>
 		/// <param name="message">Message key.</param>
 		void AddAlert(string template, string message);

 		/// <summary>
 		/// Add a formatted "Alert" error message
 		/// for the given field key via the FieldTable.
 		/// </summary>
 		/// <param name="key">Key from the FieldTable</param>
 		void AddAlertForField(string key);

 		/// <summary>
 		/// Add a formatted "Required" error message
 		/// for the given field key via the FieldTable.
 		/// </summary>
 		/// <param name="key">Key from the FieldTable</param>
 		void AddAlertRequired(string key);

 		/// <summary>
 		/// Indicate whether alerts exist.
 		/// </summary>
 		/// <returns>True if there are alerts.</returns>
 		///
 		bool HasAlerts { get; }

 		/// <summary>
 		/// Record an Exception, if thrown.
 		/// </summary>
 		///
 		Exception Fault { get; set; }

 		/// <summary>
 		/// Indicate whether an Exception was caught.
 		/// </summary>
 		/// <returns>True if an Exception was caught.</returns>
 		///
 		bool HasFault { get; }

 		/// <summary>
 		/// Indicate whether context is free of fault and alerts.
 		/// </summary>
 		/// <returns>True if there are no fault or alerts.</returns>
 		///
 		bool IsNominal { get; }

 		/// <summary>
 		/// Record hint (advisory or warning) messages (!errors),
 		/// keyed by the field causing the message,
 		/// or to a magic global key.
 		/// </summary>
 		///
 		IDictionary Hints { get; set; }

 		/// <summary>
 		/// Add a hint, creating the context if needed.
 		/// </summary>
 		/// <remarks><p>
 		/// Multiple hints can be added for a key and
 		/// retrieved as a List.
 		/// </p></remarks>
 		/// <param name="template">Message template.</param>
 		/// <param name="message">Message key.</param>
 		///
 		void AddHint(string template, string message);

 		/// <summary>
 		/// Add a hint under the "global" key.
 		/// </summary>
 		/// <param name="template">Message template.</param>
 		///
 		void AddHint(string template);

 		/// <summary>
 		/// Indicate whether hints exist.
 		/// </summary>
 		/// <returns>True if there are hints.</returns>
 		///
 		bool HasHints { get; }

 		#endregion
 	}
 }
	/*
	* Copyright 2005 The Apache Software Foundation.
	*
	* Licensed under the Apache License, Version 2.0 (the "License");
	* you may not use this file except in compliance with the License.
	* You may obtain a copy of the License at
	*
	* http://www.apache.org/licenses/LICENSE-2.0
	*
	* Unless required by applicable law or agreed to in writing, software
	* distributed under the License is distributed on an "AS IS" BASIS,
	* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
	* See the License for the specific language governing permissions and
	* limitations under the License.
	*/
	using System;
	using System.Collections;
	using Agility.Core;
	using Nexus.Core.Profile;
	using Nexus.Core.Tables;

	namespace Nexus.Core
	{
	/// <summary>
	/// Exchange data between business and presentation layers [OVR-7].
	/// </summary>
	/// <remarks><p>
	/// An IRequestContext can predefine whatever properties we need for
	/// storing input, output, messages, and other common attributes,
	/// including Locale (or Culture) and user credentials.
	/// </p><p>
	/// A key member is the FieldTable.
	/// The FieldTable uses XForms terminology for its members
	/// and IRequestContext members follow suit.
	/// For example, "errors" are called "Alerts" and generic
	/// messages are called "Hints,
	/// since these are terms used by the FieldTable and XForms.
	/// </p></remarks>
	///
	public interface IRequestContext : IContext
	{
	#region Processing

	/// <summary>
	/// Identify the top-level Command (or Chain) processing
	/// this Context.
	/// </summary>
	/// <remarks><P>
	/// The Command property corresponds to ID of INexusCommand
	/// for the initial Command or Chain.
	/// </P></remarks>
	///
	string Command { get; set; }

	/// <summary>
	/// Provide the top-level Command (or Chain) processing this Context.
	/// </summary>
	/// <remarks><p>
	/// Command corresponds to ID of INexusCommand for the
	/// initial Command or Chain.
	/// </p></remarks>
	///
	IRequestCommand CommandBin { get; set; }


	/// <summary>
	/// Provide the FieldTable for this Context.
	/// </summary>
	/// <remarks><p>
	/// The default implementation uses the Catalog to inject the global
	/// Field Table reference.
	/// The Context, and members with access to a Context,
	/// can use the FieldTable to validate and format values,
	/// and even to create controls that display values.
	/// </p></remarks>
	///
	IFieldTable FieldTable { get; set; }

	/// <summary>
	/// User profile, which includes user ID and Locale.
	/// </summary>
	IProfile Profile { get; set; }

	/// <summary>
	/// Return true if an Outcome object is present.
	/// </summary>
	/// <returns>True if an Outcome context is present.</returns>
	///
	bool HasOutcome { get; }

	/// <summary>
	/// Return a IList stored under the Command ID, if any.
	/// </summary>
	/// <remarks><p>
	/// Some Commands returns List of values.
	/// So that Commands can work together as part of a Chain,
	/// list-based Commands are expected to store the
	/// list under their own Command ID.
	/// Outcome is a convenience method to access the
	/// initial or "outermost" Command or Chain ID.
	/// </p>
	/// <p>
	/// To allow use as subcommands in a Chain,
	/// IRequestCommand implementations should prefer the idiom
	/// <code>Context[ID] = object</code>
	/// to using the Outcome directly.
	/// Since they might not be the initial Command,
	/// but rather a subcommand, or link, in a Chain.
	/// </p><p>
	/// Outcome is more convenient to presentation layer clients,
	/// who are looking for the top-level output,
	/// rather than output of a particular subcommand.
	/// </p><p>
	/// As mentioned, both Outcome and the context[ID] idiom
	/// can be used by Command that return lists of values.
	/// Commands that return a single set of fields
	/// can store the result directly in the main Context.
	/// This strategy allows one Command to obtain field values
	/// to be used by another Command
	/// (like piping output between Unix shell commands.)
	/// </p><p>
	/// Note that "Outcome" is an "alias" to an entry in
	/// this context.
	/// Unlike FieldState, Outcome is not a subcontext
	/// in its own right.
	/// </p></remarks>
	///
	object Outcome { get; set; }

	/// <summary>
	/// Indicate whether a Criteria is present.
	/// </summary>
	/// <returns>True if a Criteria is present.</returns>
	bool HasCriteria();

	/// <summary>
	/// Provide an optional subcontext containing input or output
	/// values, usually expressed as display strings.
	/// </summary>
	/// <remarks>
	/// <p>
	/// Criteria is provided for Commands that accept input
	/// from other components which may need to be validated,
	/// converted, or formatted before use.
	/// If the proposed FieldState is accepted,
	/// the entries may be merged into the root Context,
	/// perhaps after type conversion or formatting tasks.
	/// If the proposed FieldState is not accepted,
	/// the entries are not merged into the root Context,
	/// and there should be Errors or a Fault explaining
	/// why the FieldState (e.g input) cannot be accepted.
	/// </p>
	/// <p>
	/// In practice, it is expected, but not required, that
	/// all the FieldState entries will contain string values.
	/// </p>
	/// <p>
	/// Commands should only act on the Criteria in order
	/// to transfer values between the FieldState and the
	/// root Context.
	/// Conventional Commands will look to the root Context
	/// for the state and make any expected changes
	/// or additions directly to the root context.
	/// FieldState is not expected to be used by a Commands
	/// unless input is being submitted from an untrusted or
	/// naive component, or needs to be transformed for use
	/// by a display component.
	/// </p>
	/// </remarks>
	IDictionary Criteria { get; set; }

	#endregion

	#region Messaging

	string FormatTemplate(string template, string value);

	/// <summary>
	/// Record a list of alert (or error) messages,
	/// keyed by the field causing the message,
	/// or to a magic global key.
	/// </summary>
	/// <remark><p>
	/// TODO: Refactor as NameValueCollection ?
	/// </p></remark>
	///
	IDictionary Alerts { get; set; }

	/// <summary>
	/// Add an alert message under the "global" key.
	/// </summary>
	/// <param name="template">Message template.</param>
	///
	void AddAlert(string template);

	/// <summary>
	/// Add an alert message, creating the context if needed.
	/// </summary>
	/// <remarks>
	/// Multiple messages can be added for a key and retrieved as a List.
	/// </remarks>
	/// <param name="template">Message template.</param>
	/// <param name="message">Message key.</param>
	void AddAlert(string template, string message);

	/// <summary>
	/// Add a formatted "Alert" error message
	/// for the given field key via the FieldTable.
	/// </summary>
	/// <param name="key">Key from the FieldTable</param>
	void AddAlertForField(string key);

	/// <summary>
	/// Add a formatted "Required" error message
	/// for the given field key via the FieldTable.
	/// </summary>
	/// <param name="key">Key from the FieldTable</param>
	void AddAlertRequired(string key);

	/// <summary>
	/// Indicate whether alerts exist.
	/// </summary>
	/// <returns>True if there are alerts.</returns>
	///
	bool HasAlerts { get; }

	/// <summary>
	/// Record an Exception, if thrown.
	/// </summary>
	///
	Exception Fault { get; set; }

	/// <summary>
	/// Indicate whether an Exception was caught.
	/// </summary>
	/// <returns>True if an Exception was caught.</returns>
	///
	bool HasFault { get; }

	/// <summary>
	/// Indicate whether context is free of fault and alerts.
	/// </summary>
	/// <returns>True if there are no fault or alerts.</returns>
	///
	bool IsNominal { get; }

	/// <summary>
	/// Record hint (advisory or warning) messages (!errors),
	/// keyed by the field causing the message,
	/// or to a magic global key.
	/// </summary>
	///
	IDictionary Hints { get; set; }

	/// <summary>
	/// Add a hint, creating the context if needed.
	/// </summary>
	/// <remarks><p>
	/// Multiple hints can be added for a key and
	/// retrieved as a List.
	/// </p></remarks>
	/// <param name="template">Message template.</param>
	/// <param name="message">Message key.</param>
	///
	void AddHint(string template, string message);

	/// <summary>
	/// Add a hint under the "global" key.
	/// </summary>
	/// <param name="template">Message template.</param>
	///
	void AddHint(string template);

	/// <summary>
	/// Indicate whether hints exist.
	/// </summary>
	/// <returns>True if there are hints.</returns>
	///
	bool HasHints { get; }

	#endregion
	}
	}