tecgraf.javautils.xml
Class XMLElement

java.lang.Object
  tecgraf.javautils.xml.XMLElement

All Implemented Interfaces:

XMLElementInterface

Direct Known Subclasses:

XMLBasicElement, XMLDataElement

public abstract class XMLElement
extends Object
implements XMLElementInterface

Classe-base para todos os elementos XML, cuja visibilidade está restrita ao pacote; classes da aplicação que modelam elementos XML devem extender XMLElement ou XMLLeafElement.

Author:

André Oliveira da Costa

Constructor Summary

protected	XMLElement() Inicializa a tabela de conversão de XML para texto, usada na conversão de &lt; para <, p.ex.
protected	XMLElement(String tagName) Constrói um elemento recebendo sua tag como parâmetro.

Method Summary

XMLElementInterface	appendValue(String text, boolean newLine) Adiciona um valor ao elemento (append).
String	convertTextToXML(String text) Deprecated.
void	convertValueFromXML() Converte o valor associado ao elemento para texto (converte sequências de caracteres XML para seus correspondentes ASCII).
Object	getAppContextObject() Retorna o contexto da aplicação associado ao elemento XML.
Object	getAppObject() Retorna o objeto da aplicação associado ao elemento XML.
boolean	getAttributeBooleanValue(String name) Retorna o valor de um atributo como boolean.
double	getAttributeDoubleValue(String name) Retorna o valor de um atributo como double.
int	getAttributeIntValue(String name) Retorna o valor de um atributo como int.
List<? extends XMLAttribute>	getAttributes() Retorna uma cópia read-only da lista de atributos.
String	getAttributeStrValue(String name) Consulta ao valor de um atributo.
double	getDoubleValue() Retorna o valor do elemento como um double.
float	getFloatValue() Retorna o valor do elemento como um float.
int	getIntValue() Retorna o valor do elemento como um int.
long	getLongValue() Retorna o valor do elemento como um long.
String	getStrValue() Retorna o valor do elemento como texto.
String	getStrValue(boolean escapeChars) Retorna o valor associado ao elemento, com a opção de ser feito escape dos caracteres problemáticos (<, >, & etc.).
String	getTag() Retorna a tag associada ao elemento.
boolean	hasAttribute(String name) Consulta da existencia de um atributo.
boolean	hasValue() Consulta da existencia de valor.
boolean	isEmpty() Indica se o elemento não possui valor (hasValue() == false) ou se o valor é constituído apenas por espaços ou terminadores de linha.
XMLElementInterface	newAttribute(String name, boolean boolValue) Define um novo atributo com valor booleano para o elemento.
XMLElementInterface	newAttribute(String name, double doubleValue) Define um novo atributo com valor double para o elemento.
XMLElementInterface	newAttribute(String name, Enum<?> enumValue) Instancia um novo atributo que tem como valor uma constante de um Enum.
XMLElementInterface	newAttribute(String name, int intValue) Define um novo atributo com valor inteiro para o elemento.
XMLElementInterface	newAttribute(String name, long longValue) Define um novo atributo com valor inteiro (long) para o elemento.
XMLElementInterface	newAttribute(String name, String strValue) Define um novo atributo para o elemento.
XMLElementInterface	newAttributeList(List<XMLAttribute> newAttrs) Redefine os atributos do elemento a partir de uma lista externa.
void	newCharsEvent(char[] charArray, int start, int length) Evento SAX associado à leitura de caracteres associados ao valor do elemento XML.
void	resetAttributeList() Reinicializa a lista de atributos do elemento.
XMLElementInterface	resetValue() Define o valor "vazio" para o elemento (na verdade, remove o valor)
XMLElementInterface	setAppContextObject(Object contextObject) Associa um contexto da aplicação ao elemento XML.
XMLElementInterface	setAppObject(Object appObject) Define o objeto da aplicação associado ao elemento.
XMLElementInterface	setTag(String tag) Define a tag do elemento.
XMLElementInterface	setValue(double value) Define um valor double para o elemento, convertendo-o para texto.
XMLElementInterface	setValue(String value) Define o valor do elemento.
void	startTag() Implementação default (vazia) para a callback de início do processamento de um elemento.
void	writeAttributes(Writer stream) Escreve os atributos do elemento na forma nome="valor", na ordem em que estes foram armazenados.
static void	writeAttributes(Writer writer, List<? extends XMLAttribute> attributes) Escreve uma lista de atributos no stream corrente, na forma nome="valor".
void	writeEndTag(Writer stream) Escreve a tag de fechamento do elemento, sem identação.
void	writeEndTag(Writer stream, String ident) Escreve a tag de fechamento do elemento.
void	writeStartTag(Writer stream, String ident) Escreve a tag de abertura do elemento com seus respectivos atributos, sem anexar fim-de-linha.
void	writeStartTagln(Writer stream, String ident) Escreve a tag de abertura do elemento com seus respectivos atributos, anexando um fim-de-linha ao final da mesma.
void	writeValue(Writer stream) Escreve o valor do elemento.
static String	xmlEncode(String text) Deprecated.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Methods inherited from interface tecgraf.javautils.xml.XMLElementInterface

endTag, write

Constructor Detail

XMLElement

protected XMLElement()

Inicializa a tabela de conversão de XML para texto, usada na conversão de &lt; para <, p.ex.

XMLElement

protected XMLElement(String tagName)

Constrói um elemento recebendo sua tag como parâmetro.

Parameters:

tagName - tag

Method Detail

newCharsEvent

public void newCharsEvent(char[] charArray,
                          int start,
                          int length)

Evento SAX associado à leitura de caracteres associados ao valor do elemento XML. Esta implementação anexa os caracteres ao valor do elemento.

Specified by:

newCharsEvent in interface XMLElementInterface

Parameters:

charArray - array de caracteres contendo os chars lidos

start - início dos dados no array

length - quantidade de caracteres lidos

See Also:

XMLElementInterface.newCharsEvent(char[],int,int), XMLBasicHandler.characters(char[], int, int)

convertValueFromXML

public final void convertValueFromXML()

Converte o valor associado ao elemento para texto (converte sequências de caracteres XML para seus correspondentes ASCII). No caso desta implementação, converte também o buffer temporário associado ao valor para uma string. Só a partir deste momento os métodos que consultam e usam o valor do elemento podem ser executados. Executado pelo handler quando termina o processamento do elemento.

Specified by:

convertValueFromXML in interface XMLElementInterface

See Also:

XMLElementInterface.convertValueFromXML(), XMLBasicHandler.endElement(String, String, String), getStrValue(), hasValue(), isEmpty()

convertTextToXML

@Deprecated
public String convertTextToXML(String text)

Deprecated.

Converte texto ASCII para XML, fazendo escape dos caracteres <, > e &.

Specified by:

convertTextToXML in interface XMLElementInterface

Parameters:

text - texto.

Returns:

texto convertido para XML

See Also:

XMLElementInterface.convertTextToXML(java.lang.String)

xmlEncode

@Deprecated
public static String xmlEncode(String text)

Deprecated.

Codifica texto para XML:

• & para &amp;
• > para &gt;
• < para &lt;

Parameters:

text - - texto a ser convertido

Returns:

nova string com o texto convertido

appendValue

public final XMLElementInterface appendValue(String text,
                                             boolean newLine)

Adiciona um valor ao elemento (append).

Specified by:

appendValue in interface XMLElementInterface

Parameters:

text - valor textual a ser acrescido. Se for null não é considerado

newLine - flag indicativo de quebra de linha após a acréscimo.

Returns:

o próprio objeto (para encadeamento de operações)

See Also:

XMLElementInterface.appendValue(java.lang.String,boolean)

resetValue

public final XMLElementInterface resetValue()

Define o valor "vazio" para o elemento (na verdade, remove o valor)

Specified by:

resetValue in interface XMLElementInterface

Returns:

o próprio objeto (para encadeamento de operações)

See Also:

XMLElementInterface.resetValue()

setValue

public final XMLElementInterface setValue(String value)

Define o valor do elemento.

Specified by:

setValue in interface XMLElementInterface

Parameters:

value - o valor a ser usado.

Returns:

o próprio objeto (para encadeamento de operações)

See Also:

XMLElementInterface.setValue(java.lang.String)

setValue

public final XMLElementInterface setValue(double value)

Define um valor double para o elemento, convertendo-o para texto.

Specified by:

setValue in interface XMLElementInterface

Parameters:

value - o valor double a ser ajustado.

Returns:

o próprio objeto (para encadeamento de operações)

See Also:

XMLElementInterface.setValue(double)

setTag

public final XMLElementInterface setTag(String tag)

Define a tag do elemento.

Specified by:

setTag in interface XMLElementInterface

Parameters:

tag - tag associada ao elemento

Returns:

o próprio objeto (para encadeamento de operações)

See Also:

XMLElementInterface.setTag(java.lang.String)

getTag

public final String getTag()

Retorna a tag associada ao elemento.

Specified by:

getTag in interface XMLElementInterface

Returns:

a tag do elemento.

See Also:

XMLElementInterface.getTag()

getStrValue

public String getStrValue(boolean escapeChars)

Retorna o valor associado ao elemento, com a opção de ser feito escape dos caracteres problemáticos (<, >, & etc.).

Parameters:

escapeChars - se igual a true, os caracteres problemáticos serão tratados

Returns:

valor do elemento

Throws:

IllegalStateException - se o elemento ainda está sendo processado

getStrValue

public String getStrValue()

Retorna o valor do elemento como texto. Se não há valor associado, retorna uma string vazia.

Specified by:

getStrValue in interface XMLElementInterface

Returns:

o valor do elemento (como texto) ou uma string vazia

Throws:

IllegalStateException - se o elemento ainda está sendo processado

See Also:

XMLElementInterface.getStrValue()

getFloatValue

public final float getFloatValue()

Retorna o valor do elemento como um float. Caso a conversão para texto não seja possível, lança XMLParseException.

Specified by:

getFloatValue in interface XMLElementInterface

Returns:

o valor como um float.

Throws:

IllegalStateException - se o elemento ainda está sendo processado

See Also:

XMLElementInterface.getFloatValue()

getDoubleValue

public final double getDoubleValue()

Retorna o valor do elemento como um double. Caso a conversão para texto não seja possível, lança XMLParseException.

Specified by:

getDoubleValue in interface XMLElementInterface

Returns:

o valor como um double.

Throws:

IllegalStateException - se o elemento ainda está sendo processado

See Also:

XMLElementInterface.getDoubleValue()

getIntValue

public final int getIntValue()

Retorna o valor do elemento como um int. Caso a conversão para texto não seja possível, lança XMLParseException.

Specified by:

getIntValue in interface XMLElementInterface

Returns:

o valor como um int.

Throws:

IllegalStateException - se o elemento ainda está sendo processado

See Also:

XMLElementInterface.getIntValue()

getLongValue

public final long getLongValue()

Retorna o valor do elemento como um long. Caso a conversão para texto não seja possível, lança XMLParseException.

Specified by:

getLongValue in interface XMLElementInterface

Returns:

o valor como um long.

Throws:

IllegalStateException - se o elemento ainda está sendo processado

See Also:

XMLElementInterface.getLongValue()

newAttribute

public final XMLElementInterface newAttribute(String name,
                                              String strValue)

Define um novo atributo para o elemento. FIXME atualmente, permite múltiplas ocorrências de um atributo (ver observação em getAttributeStrValue())

Specified by:

newAttribute in interface XMLElementInterface

Parameters:

name - o nome do atributo.

strValue - o valor do atributo (string).

Returns:

o próprio objeto (para encadeamento de operações)

See Also:

XMLElementInterface.newAttribute(java.lang.String,java.lang.String)

newAttribute

public XMLElementInterface newAttribute(String name,
                                        Enum<?> enumValue)

Instancia um novo atributo que tem como valor uma constante de um Enum. O método Enum.toString() é usado para obter o valor a ser associado ao atributo.

Specified by:

newAttribute in interface XMLElementInterface

Parameters:

name - - nome do atributo

enumValue - - valor de enumeração

Returns:

o próprio objeto (para encadeamento de operações)

newAttribute

public final XMLElementInterface newAttribute(String name,
                                              int intValue)

Define um novo atributo com valor inteiro para o elemento.

Specified by:

newAttribute in interface XMLElementInterface

Parameters:

name - o nome do atributo.

intValue - o valor do atributo (inteiro).

Returns:

o próprio objeto (para encadeamento de operações)

See Also:

XMLElementInterface.newAttribute(java.lang.String,int)

newAttribute

public final XMLElementInterface newAttribute(String name,
                                              long longValue)

Define um novo atributo com valor inteiro (long) para o elemento.

Specified by:

newAttribute in interface XMLElementInterface

Parameters:

name - o nome do atributo.

longValue - o valor do atributo (inteiro long).

Returns:

o próprio objeto (para encadeamento de operações)

See Also:

XMLElementInterface.newAttribute(java.lang.String,int)

newAttribute

public XMLElementInterface newAttribute(String name,
                                        boolean boolValue)

Define um novo atributo com valor booleano para o elemento. true será gravado como "TRUE", e false como "FALSE".

Specified by:

newAttribute in interface XMLElementInterface

Parameters:

name - o nome do atributo.

boolValue - o valor do atributo (booleano).

Returns:

o próprio objeto (para encadeamento de operações)

See Also:

XMLElementInterface.newAttribute(java.lang.String,boolean)

newAttribute

public final XMLElementInterface newAttribute(String name,
                                              double doubleValue)

Define um novo atributo com valor double para o elemento.

Specified by:

newAttribute in interface XMLElementInterface

Parameters:

name - o nome do atributo.

doubleValue - o valor do atributo (double).

Returns:

o próprio objeto (para encadeamento de operações)

See Also:

XMLElementInterface.newAttribute(java.lang.String,double)

newAttributeList

public final XMLElementInterface newAttributeList(List<XMLAttribute> newAttrs)

Redefine os atributos do elemento a partir de uma lista externa. A lista já deve conter elementos do tipo XMLAttribute.

Specified by:

newAttributeList in interface XMLElementInterface

Parameters:

newAttrs - lista de novos atributos.

Returns:

o próprio objeto (para encadeamento de operações)

See Also:

XMLElementInterface.newAttributeList(java.util.List)

resetAttributeList

public final void resetAttributeList()

Reinicializa a lista de atributos do elemento.

Specified by:

resetAttributeList in interface XMLElementInterface

See Also:

XMLElementInterface.resetAttributeList()

hasAttribute

public final boolean hasAttribute(String name)

Consulta da existencia de um atributo.

Specified by:

hasAttribute in interface XMLElementInterface

Parameters:

name - nome do atributo.

Returns:

flag indicativo.

See Also:

XMLElementInterface.hasAttribute(java.lang.String)

hasValue

public final boolean hasValue()

Consulta da existencia de valor. Observar que qualquer caracter (incluindo espaços em branco e terminadores de linha) configura a existência de valor.

• <tag></tag> - hasValue() == false
• <tag> </tag> - hasValue() == true
• <tag>
  </tag> - hasValue() == true
• <tag>qualquer coisa</tag> - hasValue() == true

Specified by:

hasValue in interface XMLElementInterface

Returns:

flag indicativo.

Throws:

IllegalStateException - se o elemento ainda está sendo processado

See Also:

XMLElementInterface.hasValue(), isEmpty()

isEmpty

public final boolean isEmpty()

Indica se o elemento não possui valor (hasValue() == false) ou se o valor é constituído apenas por espaços ou terminadores de linha.

• <tag></tag> - isEmpty() == true
• <tag> </tag> - isEmpty() == true
• <tag>
  </tag> - isEmpty() == true
• <tag>qualquer coisa diferente de espaços</tag> - isEmpty() == false

Specified by:

isEmpty in interface XMLElementInterface

Returns:

true se o valor do elemento é uma string vazia ou é constituído apenas por espaços ou terminadores de linha

Throws:

IllegalStateException - se o elemento ainda está sendo processado

See Also:

hasValue()

getAttributeStrValue

public String getAttributeStrValue(String name)

Consulta ao valor de um atributo. Esta implementação usa busca sequencial. Se for o caso, implementar um mapeamento auxiliar (p.ex. mapa [nome --> índice]) para otimizar o acesso. Outra alternativa seria usar aqui mapas [nome --> {valor, índice}], e ordenar os valores pelo índice (talvez em uma estrutura auxiliar) quando for necessário exibi-los.

Specified by:

getAttributeStrValue in interface XMLElementInterface

Parameters:

name - nome do atributo.

Returns:

valor do atributo como String

See Also:

XMLElementInterface.getAttributeStrValue(java.lang.String)

getAttributeBooleanValue

public boolean getAttributeBooleanValue(String name)

Retorna o valor de um atributo como boolean.

Specified by:

getAttributeBooleanValue in interface XMLElementInterface

Parameters:

name - nome do atributo.

Returns:

true se o atributo tem como valor a string "true" (case-insensitive), false caso contrário

See Also:

XMLElementInterface.getAttributeBooleanValue(java.lang.String)

getAttributeIntValue

public final int getAttributeIntValue(String name)

Retorna o valor de um atributo como int.

Specified by:

getAttributeIntValue in interface XMLElementInterface

Parameters:

name - nome do atributo.

Returns:

inteiro associado ao valor. Se a conversão não for possível, lança XMLParseException

See Also:

XMLElementInterface.getAttributeIntValue(java.lang.String)

getAttributeDoubleValue

public double getAttributeDoubleValue(String name)

Retorna o valor de um atributo como double.

Specified by:

getAttributeDoubleValue in interface XMLElementInterface

Parameters:

name - nome do atributo.

Returns:

double associado ao valor. Se a conversão não for possível, lança XMLParseException

See Also:

XMLElementInterface.getAttributeIntValue(java.lang.String)

getAttributes

public List<? extends XMLAttribute> getAttributes()

Retorna uma cópia read-only da lista de atributos.

Specified by:

getAttributes in interface XMLElementInterface

Returns:

cópia read-only da lista de atributos.

See Also:

XMLElementInterface.getAttributes()

writeStartTag

public void writeStartTag(Writer stream,
                          String ident)
                   throws IOException

Escreve a tag de abertura do elemento com seus respectivos atributos, sem anexar fim-de-linha.

Specified by:

writeStartTag in interface XMLElementInterface

Parameters:

stream - stream de saída

ident - identação

Throws:

IOException - se houver algum erro de escrita

writeStartTagln

public void writeStartTagln(Writer stream,
                            String ident)
                     throws IOException

Escreve a tag de abertura do elemento com seus respectivos atributos, anexando um fim-de-linha ao final da mesma.

Specified by:

writeStartTagln in interface XMLElementInterface

Parameters:

stream - stream de saída

ident - identação

Throws:

IOException - se houver algum erro de escrita

writeAttributes

public void writeAttributes(Writer stream)
                     throws IOException

Escreve os atributos do elemento na forma nome="valor", na ordem em que estes foram armazenados.

Specified by:

writeAttributes in interface XMLElementInterface

Parameters:

stream - de saída

Throws:

IOException - se houver algum erro de escrita

writeAttributes

public static void writeAttributes(Writer writer,
                                   List<? extends XMLAttribute> attributes)
                            throws IOException

Escreve uma lista de atributos no stream corrente, na forma nome="valor".

Parameters:

writer - stream de saída

attributes - lista de XMLAttribute

Throws:

IOException - se houver algum erro de escrita

writeValue

public void writeValue(Writer stream)
                throws IOException

Escreve o valor do elemento. Os caracteres &, < e > são devidamente codificador para HTML.

Specified by:

writeValue in interface XMLElementInterface

Parameters:

stream - stream de saída

Throws:

IOException - se houver algum erro de escrita

writeEndTag

public void writeEndTag(Writer stream,
                        String ident)
                 throws IOException

Escreve a tag de fechamento do elemento.

Specified by:

writeEndTag in interface XMLElementInterface

Parameters:

stream - stream de saída

ident - identação

Throws:

IOException - se houver algum erro de escrita

writeEndTag

public final void writeEndTag(Writer stream)
                       throws IOException

Escreve a tag de fechamento do elemento, sem identação. Usado no fechamento de data elements.

Specified by:

writeEndTag in interface XMLElementInterface

Parameters:

stream - stream de saída

Throws:

IOException - se houver algum erro de escrita

startTag

public void startTag()

Implementação default (vazia) para a callback de início do processamento de um elemento.

Specified by:

startTag in interface XMLElementInterface

See Also:

XMLElementInterface.startTag()

setAppObject

public final XMLElementInterface setAppObject(Object appObject)

Define o objeto da aplicação associado ao elemento. Usado tipicamente durante o processo de escrita dos elementos, onde esses são criados a partir de objetos da aplicação e precisam extrair destes os dados que serão escritos no XML.

Specified by:

setAppObject in interface XMLElementInterface

Parameters:

appObject - objeto da aplicação associado ao elemento XML

Returns:

o próprio elemento, para encadeamento de operações

getAppObject

public final Object getAppObject()

Retorna o objeto da aplicação associado ao elemento XML. Este objeto não necessariamente precisa existir (i.e. o objeto pode ser null).

Specified by:

getAppObject in interface XMLElementInterface

Returns:

o objeto da aplicação associado ao elemento XML

setAppContextObject

public final XMLElementInterface setAppContextObject(Object contextObject)

Associa um contexto da aplicação ao elemento XML.

Specified by:

setAppContextObject in interface XMLElementInterface

Parameters:

contextObject - objeto representativo de contexto da aplicacao.

Returns:

o próprio elemento, para encadeamento de operações

getAppContextObject

public final Object getAppContextObject()

Retorna o contexto da aplicação associado ao elemento XML.

Specified by:

getAppContextObject in interface XMLElementInterface

Returns:

o objeto representativo de contexto da aplicacao.