/**********************************************************************
This file is part of the OpenEAI sample, reference implementation,
and deployment management suite created by Tod Jackson
(tod@openeai.org) and Steve Wheat (steve@openeai.org) at
the University of Illinois Urbana-Champaign.
Copyright (C) 2002 The OpenEAI Software Foundation
This program is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 2 of the License, or
(at your option) any later version.
This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU General Public License for more details.
You should have received a copy of the GNU General Public License
along with this program; if not, write to the Free Software
Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
For specific licensing details and examples of how this software
can be used to implement integrations for your enterprise, visit
http://www.OpenEai.org/licensing.
*/
package org.any_openeai_enterprise.gateways.simple;
// Core Java
import java.util.ArrayList;
import javax.jms.*;
// JDOM
import org.jdom.Document;
import org.jdom.Element;
// General OpenEAI foundation
import org.openeai.config.CommandConfig;
import org.openeai.config.PropertyConfig;
import org.openeai.config.EnterpriseConfigurationObjectException;
import org.openeai.xml.XmlDocumentReader;
import org.openeai.xml.XmlDocumentReaderException;
import org.openeai.jms.consumer.commands.RequestCommand;
import org.openeai.jms.consumer.commands.RequestCommandImpl;
import org.openeai.jms.consumer.commands.CommandException;
/**
* This class replies with a status of failure and an error to any request
* message.
* <P>
* Specifically, this command handles any request message and replies with a
* org.openeai.CoreMessaging/Generic/Response-Reply message. This command is
* intended to be deployed into gateways to return a predetermined error
* message when the application that the gateway exposes is intentionally
* unavailable.
* <P>
* <B>Configuration Parameters:</B>
* <P>
* This command expects exactly one properties object in the command
* configuration with the following properties. The properties object may
* have any name, because it is retrieved by type.
* <P>
* <TABLE BORDER=2 CELLPADDING=5 CELLSPACING=2>
* <TR>
* <TH>Name</TH>
* <TH>Required</TH>
* <TH>Description</TH>
* </TR>
* <TR HALIGN="left" VALIGN="top">
* <TD>responseDocumentUri</TD>
* <TD>yes</TD>
* <TD>URI for retrieving the primed
* org.openeai.CoreMessaging/Generic/Response-Reply document</TD>
* </TR>
* <TR HALIGN="left" VALIGN="top">
* <TD>errorType</TD>
* <TD>yes</TD>
* <TD>The value for the Error/@type attribute that will be returned in the
* reply. This may have a value of 'application' or 'system' according to the
* OpenEAI Message Protocol.</TD>
* </TR>
* <TR HALIGN="left" VALIGN="top">
* <TD>errorNumber</TD>
* <TD>yes</TD>
* <TD>The value for the Error/ErrorNumber element that will be returned in the
* reply. This may have any value desired by the administrator; however, this
* will most likely be an OpenEAI-2000 or other appropriate error message in the
* standard series of OpenEAI messages that convey the unavailability of a
* gateway or service.</TD>
* </TR>
* <TR HALIGN="left" VALIGN="top">
* <TD>errorDescription</TD>
* <TD>yes</TD>
* <TD>The value for the Error/ErrorDescription element appropriate to the error
* number specified by the errorNumber property.</TD>
* </TR>
* </TABLE>
* <P>
* <B>Error Messages:</B>
* <P>
* This command is intended to provide a reply with exactly one error. It could
* be any error, because the error is configurable as outlined in the
* configuration parameters above. However, since the purpose of this command is
* generally to communicate the temporary, intentional unavailability of an
* application, gateway, or service, the error will most frequently be a variant
* of the following:
* <P>
* <TABLE BORDER=2 CELLPADDING=5 CELLSPACING=2>
* <TR>
* <TH>Code</TH>
* <TH>Type</TH>
* <TH>Description</TH>
* <TH>Explanation</TH>
* </TR>
* <TR HALIGN="left" VALIGN="top">
* <TD><NOBR>OpenEAI-2000</NOBR></TD>
* <TD>application</TD>
* <TD>Gateway, service, or application temporarily unavailable.
* [Name of the gateway, service, or application] is unavailable due to
* [state reason] and will be available again at approximately [state
* next available time].</TD>
* <TD>This gateway, service, or underlying application is temporarily and
* intentionally unavailable for reasons that should be stated in the
* ErrorDescription.</TD>
* </TR>
* </TABLE>
* <P>
* @author Steve Wheat (steve@openeai.org)
* @version 3.0 beta - 21 November 2002
*/
public class FailureRequestCommand extends RequestCommandImpl implements
RequestCommand {
private Document m_responseDoc = null;
private ArrayList m_errors = new ArrayList();
/**
* The constructor
*/
public FailureRequestCommand(CommandConfig cConfig) throws
InstantiationException {
super(cConfig);
// Get and set the general properties for this command.
PropertyConfig pConfig = new PropertyConfig();
try {
pConfig = (PropertyConfig)getAppConfig()
.getObjectByType(pConfig.getClass().getName());
}
catch (EnterpriseConfigurationObjectException eoce) {
String errMsg = "Error retrieving a PropertyConfig object from " +
"AppConfig: The exception is: " + eoce.getMessage();
throw new InstantiationException(errMsg);
}
setProperties(pConfig.getProperties());
// Initialize the response document.
XmlDocumentReader xmlReader = new XmlDocumentReader();
try {
m_responseDoc = xmlReader.initializeDocument(getProperties()
.getProperty("responseDocumentUri"), getOutboundXmlValidation());
if (m_responseDoc == null) {
throw new InstantiationException("Missing 'responseDocumentUri' " +
"property in the deployment descriptor. Can't continue.");
}
}
catch (XmlDocumentReaderException e) {
logger.fatal("Error initializing the primed response document.");
throw new InstantiationException(e.getMessage());
}
// Get the values for the error message to be returned in every reply.
String errType = getProperties().getProperty("errorType");
if (errType == null) {
String errMsg = "Missing value for required property 'errorType' " +
"in deployment descriptor. Can't continue.";
throw new InstantiationException(errMsg);
}
logger.info("[FailureRequestCommand] errorType is: " + errType);
String errNumber = getProperties().getProperty("errorNumber");
if (errNumber == null) {
String errMsg = "Missing value for required property 'errorNumber' " +
"in deployment descriptor. Can't continue.";
throw new InstantiationException(errMsg);
}
logger.info("[FailureRequestCommand] errorNumber is: " + errNumber);
String errDesc = getProperties().getProperty("errorDescription");
if (errType == null) {
String errMsg = "Missing value for required property 'errorDescription' "
+ "in deployment descriptor. Can't continue.";
throw new InstantiationException(errMsg);
}
logger.info("[FailureRequestCommand] errorDesc is: " + errDesc);
// Build the list of errors to be returned in every reply.
m_errors.add(buildError(errType, errNumber, errDesc));
logger.info("[FailureRequestCommand] instantiated successfully.");
}
public final Message execute(int messageNumber, Message aMessage) throws
CommandException {
// Make a local copy of the response document to use in the reply.
Document localResponseDoc = (Document)m_responseDoc.clone();
// Convert the JMS Message to an XML Document
Document inDoc = null;
try {
inDoc = initializeInput(messageNumber, aMessage);
}
catch (Exception e) {
String errMsg = "Exception occurred processing input message in " +
"org.openeai.jms.consumer.commands.Command. Exception: " +
e.getMessage();
throw new CommandException(errMsg);
}
// Retrieve text portion of message.
TextMessage msg = (TextMessage)aMessage;
try {
// Clear the message body for the reply, so we do not
// have to do it later.
msg.clearBody();
}
catch (Exception e) {
String errMsg = "Error clearing the message body.";
throw new CommandException(errMsg + ". The exception is: " +
e.getMessage());
}
// Get the ControlArea from XML document.
Element eControlArea = getControlArea(inDoc.getRootElement());
// Reply with a failure and error.
String replyContents =
buildReplyDocumentWithErrors(eControlArea, localResponseDoc, m_errors);
logger.info("[FailureRequestCommand] Replying with a status of 'failure' " +
"and a preconfigured error.");
return getMessage(msg, replyContents);
}
}