/*
* 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
{
///
/// Exchange data between business and presentation layers [OVR-7].
///
///
/// An IRequestContext can predefine whatever properties we need for
/// storing input, output, messages, and other common attributes,
/// including Locale (or Culture) and user credentials.
///
/// 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.
///
///
public interface IRequestContext : IContext
{
#region Processing
///
/// Identify the top-level Command (or Chain) processing
/// this Context.
///
///
/// The Command property corresponds to ID of INexusCommand
/// for the initial Command or Chain.
///
///
string Command { get; set; }
///
/// Provide the top-level Command (or Chain) processing this Context.
///
///
/// Command corresponds to ID of INexusCommand for the
/// initial Command or Chain.
///
///
IRequestCommand CommandBin { get; set; }
///
/// Provide the FieldTable for this Context.
///
///
/// 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.
///
///
IFieldTable FieldTable { get; set; }
///
/// User profile, which includes user ID and Locale.
///
IProfile Profile { get; set; }
///
/// Return true if an Outcome object is present.
///
/// True if an Outcome context is present.
///
bool HasOutcome { get; }
///
/// Return a IList stored under the Command ID, if any.
///
///
/// 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.
///
///
/// To allow use as subcommands in a Chain,
/// IRequestCommand implementations should prefer the idiom
/// Context[ID] = object
/// to using the Outcome directly.
/// Since they might not be the initial Command,
/// but rather a subcommand, or link, in a Chain.
///
/// Outcome is more convenient to presentation layer clients,
/// who are looking for the top-level output,
/// rather than output of a particular subcommand.
///
/// 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.)
///
/// Note that "Outcome" is an "alias" to an entry in
/// this context.
/// Unlike FieldState, Outcome is not a subcontext
/// in its own right.
///
///
object Outcome { get; set; }
///
/// Indicate whether a Criteria is present.
///
/// True if a Criteria is present.
bool HasCriteria();
///
/// Provide an optional subcontext containing input or output
/// values, usually expressed as display strings.
///
///
///
/// 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.
///
///
/// In practice, it is expected, but not required, that
/// all the FieldState entries will contain string values.
///
///
/// 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.
///
///
IDictionary Criteria { get; set; }
#endregion
#region Messaging
string FormatTemplate(string template, string value);
///
/// Record a list of alert (or error) messages,
/// keyed by the field causing the message,
/// or to a magic global key.
///
///
/// TODO: Refactor as NameValueCollection ?
///
///
IDictionary Alerts { get; set; }
///
/// Add an alert message under the "global" key.
///
/// Message template.
///
void AddAlert(string template);
///
/// Add an alert message, creating the context if needed.
///
///
/// Multiple messages can be added for a key and retrieved as a List.
///
/// Message template.
/// Message key.
void AddAlert(string template, string message);
///
/// Add a formatted "Alert" error message
/// for the given field key via the FieldTable.
///
/// Key from the FieldTable
void AddAlertForField(string key);
///
/// Add a formatted "Required" error message
/// for the given field key via the FieldTable.
///
/// Key from the FieldTable
void AddAlertRequired(string key);
///
/// Indicate whether alerts exist.
///
/// True if there are alerts.
///
bool HasAlerts { get; }
///
/// Record an Exception, if thrown.
///
///
Exception Fault { get; set; }
///
/// Indicate whether an Exception was caught.
///
/// True if an Exception was caught.
///
bool HasFault { get; }
///
/// Indicate whether context is free of fault and alerts.
///
/// True if there are no fault or alerts.
///
bool IsNominal { get; }
///
/// Record hint (advisory or warning) messages (!errors),
/// keyed by the field causing the message,
/// or to a magic global key.
///
///
IDictionary Hints { get; set; }
///
/// Add a hint, creating the context if needed.
///
///
/// Multiple hints can be added for a key and
/// retrieved as a List.
///
/// Message template.
/// Message key.
///
void AddHint(string template, string message);
///
/// Add a hint under the "global" key.
///
/// Message template.
///
void AddHint(string template);
///
/// Indicate whether hints exist.
///
/// True if there are hints.
///
bool HasHints { get; }
#endregion
}
}