/**
* Constructs a new <code>State</code> object.
*
* @param name the name of this state, cannot be <code>null</code>.
* @throws IllegalArgumentException if <code>name == null</code>.
*/
State(String name) throws IllegalArgumentException {
// Check preconditions
MandatoryArgumentChecker.check("name", name);
_name = name;
}
/**
* Returns the type of the specified <code>File</code> object.
*
* <p>This method always returns a valid MIME type.
*
* @param file the file to be typed, cannot be <code>null</code>.
* @throws IllegalArgumentException if <code>file == null</code>.
*/
public String getContentType(File file) throws IllegalArgumentException {
// Check preconditions
MandatoryArgumentChecker.check("file", file);
return getContentType(file.getName());
}
/**
* Gets the value of the specified parameter.
*
* @param name the parameter element name, cannot be <code>null</code>.
* @return string containing the value of the parameter element, or <code>null</code> if the value
* is not set.
* @throws IllegalArgumentException if <code>name == null</code>.
*/
public String getParameter(String name) throws IllegalArgumentException {
// Check preconditions
MandatoryArgumentChecker.check("name", name);
return _parameters.get(name);
}
/**
* Receive notification of the end of an element.
*
* @param namespaceURI the namespace URI, can be <code>null</code>.
* @param localName the local name (without prefix); cannot be <code>null</code>.
* @param qName the qualified name (with prefix), can be <code>null</code> since <code>
* namespaceURI</code> and <code>localName</code> are only used.
* @throws IllegalArgumentException if <code>localName == null</code>.
*/
public void endElement(String namespaceURI, String localName, String qName)
throws IllegalArgumentException {
// Temporarily enter ERROR state, on success this state is left
State currentState = _state;
_state = ERROR;
// Check preconditions
MandatoryArgumentChecker.check("localName", localName);
if (currentState == ERROR) {
String detail = "Unexpected state " + currentState + " (level=" + _level + ')';
throw Utils.logProgrammingError(detail);
// Within data section
} else {
// Get the Element for which we process the end tag
Element child = _dataElementStack.pop();
// Add the child to the parent
if (_dataElementStack.size() > 0) {
Element parent = _dataElementStack.peek();
parent.add(child);
// Reset the state back from ERROR to PARSING
_state = PARSING;
} else {
_element = child;
_state = FINISHED;
}
}
_level--;
}
/**
* Parses content of a character stream to create an XML <code>Element</code> object.
*
* @param in the character stream that is supposed to contain XML to be parsed, not <code>null
* </code>.
* @return the parsed result, not <code>null</code>.
* @throws IllegalArgumentException if <code>in == null</code>.
* @throws IOException if there is an I/O error.
* @throws ParseException if the content of the character stream is not considered to be valid
* XML.
*/
public Element parse(Reader in) throws IllegalArgumentException, IOException, ParseException {
// Check preconditions
MandatoryArgumentChecker.check("in", in);
// Wrap the Reader in a SAX InputSource object
return parse(new InputSource(in));
}
@Override
public final String toString(Object value)
throws IllegalArgumentException, ClassCastException, TypeValueException {
// Check preconditions
MandatoryArgumentChecker.check("value", value);
// The argument must be a ItemList
return toString((ItemList) value);
}
/**
* Parses the specified String to create an XML <code>Element</code> object.
*
* @param text the XML text to be parsed, not <code>null</code>.
* @return the parsed result, not <code>null</code>.
* @throws IllegalArgumentException if <code>text == null</code>.
* @throws ParseException if the content of the character stream is not considered to be valid
* XML.
* @since XINS 2.0
*/
public Element parse(String text) throws IllegalArgumentException, ParseException {
// Check preconditions
MandatoryArgumentChecker.check("text", text);
try {
return parse(new StringReader(text));
} catch (IOException ioe) {
throw Utils.logProgrammingError(ioe);
}
}
/**
* Adds a new <code>Element</code> to the data element.
*
* @param element the new element to add to the result, cannot be <code>null</code>.
* @throws IllegalArgumentException if <code>element == null</code>.
* @since XINS 1.1.0
*/
protected void add(Element element) throws IllegalArgumentException {
// Check preconditions
MandatoryArgumentChecker.check("element", element);
// Lazily initialize _dataElement
if (_dataElement == null) {
_dataElement = new Element("data");
}
_dataElement.addChild(element);
}
/**
* Receive notification of the beginning of an element.
*
* @param namespaceURI the namespace URI, can be <code>null</code>.
* @param localName the local name (without prefix); cannot be <code>null</code>.
* @param qName the qualified name (with prefix), can be <code>null</code> since <code>
* namespaceURI</code> and <code>localName</code> are always used instead.
* @param atts the attributes attached to the element; if there are no attributes, it shall be
* an empty {@link Attributes} object; cannot be <code>null</code>.
* @throws IllegalArgumentException if <code>localName == null || atts == null</code>.
* @throws SAXException if the parsing failed.
*/
public void startElement(String namespaceURI, String localName, String qName, Attributes atts)
throws IllegalArgumentException, SAXException {
// Temporarily enter ERROR state, on success this state is left
State currentState = _state;
_state = ERROR;
// Make sure namespaceURI is either null or non-empty
namespaceURI = "".equals(namespaceURI) ? null : namespaceURI;
// Check preconditions
MandatoryArgumentChecker.check("localName", localName, "atts", atts);
// Increase the element depth level
_level++;
if (currentState == ERROR) {
String detail = "Unexpected state " + currentState + " (level=" + _level + ')';
throw Utils.logProgrammingError(detail);
} else {
// Find the namespace prefix
String prefix = null;
if (qName != null && qName.indexOf(':') != -1) {
prefix = qName.substring(0, qName.indexOf(':'));
}
// Construct a Element
Element element = new Element(prefix, namespaceURI, localName);
// Add all attributes
for (int i = 0; i < atts.getLength(); i++) {
String attrNamespaceURI = atts.getURI(i);
String attrLocalName = atts.getLocalName(i);
String attrValue = atts.getValue(i);
String attrQName = atts.getQName(i);
String attrPrefix = null;
if (attrQName != null && attrQName.indexOf(':') != -1) {
attrPrefix = attrQName.substring(0, attrQName.indexOf(':'));
}
element.setAttribute(attrPrefix, attrNamespaceURI, attrLocalName, attrValue);
}
// Push the element on the stack
_dataElementStack.push(element);
// Reset the state from ERROR back to PARSING
_state = PARSING;
}
}
/**
* Adds an output parameter to the result. The name and the value must both be specified.
*
* @param name the name of the output parameter, not <code>null</code> and not an empty string.
* @param value the value of the output parameter, not <code>null</code> and not an empty string.
* @throws IllegalArgumentException if <code>name == null || "".equals(name)
* || value == null || "".equals(value)</code>.
*/
protected void param(String name, String value) throws IllegalArgumentException {
// Check preconditions
MandatoryArgumentChecker.check("name", name, "value", value);
if (name.length() < 1) {
throw new IllegalArgumentException("\"\".equals(name)");
} else if (value.length() < 1) {
throw new IllegalArgumentException("\"\".equals(value)");
}
// This will erase any value set before with the same name.
_parameters.set(name, value);
}
/**
* Creates a new <code>FunctionRequest</code>, optionally indicating that the actual function
* invocation should be skipped.
*
* @param functionName the name of the function, cannot be <code>null</code>.
* @param parameters the parameters of the function requested, or <code>null</code>.
* @param dataElement the data section of the input request, or <code>null</code>.
* @param skipFunctionCall <code>true</code> if the function should not be executed; <code>false
* </code> if the function should be executed (the latter being typical)
* @throws IllegalArgumentException if <code>functionName == null</code>.
* @since XINS 2.0
*/
public FunctionRequest(
String functionName, PropertyReader parameters, Element dataElement, boolean skipFunctionCall)
throws IllegalArgumentException {
// Check preconditions
MandatoryArgumentChecker.check("functionName", functionName);
// Initialize instance fields
_functionName = functionName;
_parameters =
(parameters == null)
? PropertyReaderUtils.EMPTY_PROPERTY_READER
: PropertyReaderUtils.copyUnmodifiable(parameters);
_dataElement = dataElement;
_skipFunctionCall = skipFunctionCall;
}
/**
* Returns the type of the specified file name.
*
* <p>This method always returns a valid MIME type.
*
* @param fileName the name of the file to be typed, cannot be <code>null</code>.
* @throws IllegalArgumentException if <code>fileName == null</code>.
*/
public String getContentType(String fileName) throws IllegalArgumentException {
// Check preconditions
MandatoryArgumentChecker.check("fileName", fileName);
// Determine the extension
int index = fileName.lastIndexOf('.');
if (index > 0) {
String suffix = fileName.substring(index + 1);
// If a mapping was found, return the content type found
String type = _mappings.get(suffix);
if (type != null) {
return type;
}
}
// Fallback default
Utils.logWarning("StandardFileTypeMap: No MIME type found for file name \"" + fileName + "\".");
return "application/octet-stream";
}
/**
* Parses content of a file to create an XML <code>Element</code> object.
*
* @param file the file that is supposed to contain XML to be parsed, not <code>null</code>.
* @return the parsed result, not <code>null</code>.
* @throws IllegalArgumentException if <code>file == null</code>.
* @throws IOException if there is an I/O error, e.g. the file does not exist or is actually a
* directory.
* @throws ParseException if the content of the file is not considered to be valid XML.
* @since XINS 2.2
*/
public Element parse(File file) throws IllegalArgumentException, IOException, ParseException {
// Check preconditions
MandatoryArgumentChecker.check("file", file);
FileInputStream fis = null;
try {
fis = new FileInputStream(file);
return parse(fis);
// Enrich an I/O exception with the file name
} catch (IOException cause) {
IOException e =
new IOException(
"Failed to parse file "
+ TextUtils.quote(file.getAbsolutePath())
+ " due to an I/O error.");
e.initCause(cause);
throw e;
// Enrich a parse exception with the file name
} catch (ParseException cause) {
throw new ParseException(
"Failed to parse file " + TextUtils.quote(file.getAbsolutePath()) + '.', cause);
// Anyway, always attempt to close the input stream
} finally {
try {
if (fis != null) {
fis.close();
}
} catch (IOException ex) {
// Never mind
}
}
}
