Noções básicas sobre conversões de tipo de dados

Baixar driver JDBC

Para facilitar a conversão de tipos de dados da linguagem de programação Java para tipos de dados SQL Server, o Microsoft JDBC Driver para SQL Server fornece conversões de tipos de dados conforme exigido pela especificação JDBC. Para maior flexibilidade, todos os tipos são convertíveis para e a partir dos tipos de dados Objecto, String e byte[].

Conversões do método getter

Com base nos tipos de dados do SQL Server, o gráfico seguinte contém o mapa de conversão do driver JDBC para os métodos get<Type>() da classe SQLServerResultSet , e as conversões suportadas para os métodos get<Type> da classe SQLServerCallableStatement .

Existem três categorias de conversões suportadas pelos métodos getter do driver JDBC:

• Não-Lossy (x): Conversões para casos em que o tipo de getter é igual ou menor que o tipo de servidor subjacente. Por exemplo, ao chamar getBigDecimal numa coluna decimal de servidor subjacente, não é necessária conversão.

• Convertido (y): Conversões de tipos numéricos de servidor para tipos de linguagem Java onde a conversão é regular e segue as regras de conversão da linguagem Java. Para essas conversões, a precisão é sempre truncada — nunca arredondada — e o overflow é tratado como módulo do tipo de destino, que é de menor tamanho. Por exemplo, chamar getInt numa coluna decimal subjacente que contém "1.9999" devolverá "1", ou se o valor decimal subjacente for "3000000000", então o valor int transborda para "-1294967296".

• Dependente de Dados (z): As conversões dos tipos de carácter subjacentes para tipos numéricos exigem que os tipos de caracteres contenham valores que possam ser convertidos nesse tipo. Não são realizadas outras conversões. Se o valor for demasiado grande para o tipo de getter, o valor não é válido. Por exemplo, ao chamar getInt numa coluna varchar(50) que contém "53", o valor é devolvido como int. Contudo, se o valor subjacente for "xyz" ou "3000000000", é gerado um erro.

Seja getString for invocado num tipo de dado binary, varbinary, varbinary(max) ou image, o valor é devolvido como uma string hexadecimal.

Conversões de métodos do atualizador

Para os dados tipados em Java passados para os métodos update<Type>() da classe SQLServerResultSet , aplicam-se as seguintes conversões.

Existem três categorias de conversões suportadas pelos métodos atualizadores do driver JDBC:

• Não-Lossy (x): Conversões para casos em que o tipo de atualizador é igual ou menor do que o tipo de servidor subjacente. Por exemplo, ao chamar updateBigDecimal numa coluna decimal de servidor subjacente, não é necessária conversão.

• Convertido (y): Conversões de tipos numéricos de servidor para tipos de linguagem Java onde a conversão é regular e segue as regras de conversão da linguagem Java. Para estas conversões, a precisão é sempre truncada (nunca arredondada) e o overflow é tratado como módulo do tipo de destino (o mais pequeno). Por exemplo, chamar updateDecimal numa coluna int subjacente que contenha "1.9999" devolverá "1", ou se o valor decimal subjacente for "3000000000", então o valor int transborda para "-1294967296".

• Dependente de Dados (z): As conversões dos tipos de dados de origem subjacentes para tipos de destino exigem que os valores contidos possam ser convertidos nos tipos de destino. Não são realizadas outras conversões. Se o valor for demasiado grande para o tipo de getter, o valor não é válido. Por exemplo, se updateString for chamada numa coluna int que contém "53", a atualização é bem-sucedida; mas se o valor subjacente da String for "foo" ou "3000000000", é lançado um erro.

Quando updateString é chamada num tipo de dados de coluna binária, varbinária, varbinária(max) ou imagem , trata o valor da String como um valor hexadecimal.

Quando o tipo de dado da coluna SQL Server é XML, o valor dos dados deve ser um XML válido. Ao chamar métodos updateBytes, updateBinaryStream ou updateBlob, o valor dos dados deve ser a representação hexadecimal da cadeia dos caracteres XML. Por exemplo:

<hello>world</hello> = 0x3C68656C6C6F3E776F726C643C2F68656C6C6F3E

Note que é necessária uma marca de ordem de bytes (BOM) se os caracteres XML estiverem em codificações específicas de caracteres.

Conversões do método Setter

Para os dados tipados em Java passados para os métodos do conjunto<Type>() da classe SQLServerPreparedStatement e da classe SQLServerCallableStatement , aplicam-se as seguintes conversões.

O servidor tenta quaisquer conversões e devolve erros em caso de falha.

No caso do tipo de dados String , se o valor exceder o comprimento de VARCHAR, ele corresponde a LONGVARCHAR. De forma semelhante, NVARCHAR mapeia para LONGNVARCHAR se o valor exceder o comprimento suportado de NVARCHAR. O mesmo se aplica ao byte[]. Valores mais longos que VARBINARY tornam-se LONGVARBINARY.

Existem duas categorias de conversões suportadas pelos métodos setter do driver JDBC:

• Não-Lossy (x): Conversões para casos numéricos em que o tipo de setter é igual ou menor que o tipo de servidor subjacente. Por exemplo, ao chamar setBigDecimal numa coluna decimal de servidor subjacente, não é necessária conversão. Para conversões de numérico para carácter, o tipo de dados numérico do Java é convertido para uma String. Por exemplo, chamar setDouble com o valor "53" numa coluna varchar(50) produz um valor de carácter "53" nessa coluna de destino.

• Convertido (y): Conversões de um tipo numérico Java para um tipo numérico subjacente do servidor que é menor. Esta conversão é regular e segue as convenções de conversão do SQL Server. A precisão é sempre truncada (nunca arredondada) e o overflow gera um erro de conversão não suportado. Por exemplo, usar "updateDecimal" com o valor "1.9999" em uma coluna inteira subjacente resulta em "1" na coluna de destino; mas se "3000000000" for passado, o driver gera um erro.

• Data Dependent (z): As conversões de um tipo Java String para o tipo de dados SQL Server subjacente dependem das seguintes condições: O driver envia o valor String para SQL Server e o SQL Server realiza conversões, se necessário. Se o sendStringParametersAsUnicode estiver definido como true e o tipo de dado subjacente do SQL Server for image, o SQL Server não permite converter nvarchar em image e lança uma SQLServerException. Se o sendStringParametersAsUnicode estiver definido como falso e o tipo de dado subjacente do SQL Server for image, o SQL Server permite converter varchar em image e não lança exceções.

O SQL Server realiza as conversões e transmite erros de volta ao driver JDBC quando há problemas.

Quando o tipo de dado da coluna SQL Server é XML, o valor dos dados deve ser um XML válido. Ao chamar métodos updateBytes, updateBinaryStream ou updateBlob, o valor dos dados deve ser a representação hexadecimal da cadeia dos caracteres XML. Por exemplo:

<hello>world</hello> = 0x3C68656C6C6F3E776F726C643C2F68656C6C6F3E

Note que é necessária uma marca de ordem de bytes (BOM) se os caracteres XML estiverem em codificações específicas de caracteres.

Conversões no setObject

Para os dados tipados em Java passados para os métodos setObject(<Type>) da classe SQLServerPreparedStatement , aplicam-se as seguintes conversões.

O método setObject sem um tipo de alvo especificado usa o mapeamento padrão. No caso do tipo de dados String , se o valor exceder o comprimento de VARCHAR, ele corresponde a LONGVARCHAR. De forma semelhante, NVARCHAR mapeia para LONGNVARCHAR se o valor exceder o comprimento suportado de NVARCHAR. O mesmo se aplica ao byte[]. Valores mais longos que VARBINARY tornam-se LONGVARBINARY.

Existem três categorias de conversões suportadas pelos métodos setObject do driver JDBC:

• Não-Lossy (x): Conversões para casos numéricos em que o tipo de setter é igual ou menor que o tipo de servidor subjacente. Por exemplo, ao chamar setBigDecimal numa coluna decimal de servidor subjacente, não é necessária conversão. Para conversões de numérico para carácter, o tipo de dados numérico do Java é convertido para uma String. Por exemplo, chamar setDouble com o valor "53" numa coluna varchar(50) produzirá um valor de carácter "53" nessa coluna de destino.

• Convertido (y): Conversões de um tipo numérico Java para um tipo numérico subjacente do servidor que é menor. Esta conversão é regular e segue as convenções de conversão do SQL Server. A precisão é sempre truncada — nunca arredondada — e o overflow gera um erro de conversão não suportado. Por exemplo, usar updateDecimal com o valor "1.9999" numa coluna de tipo inteiro subjacente resulta num "1" na coluna de destino; mas se "3000000000" for passado, o driver lança um erro.

• Data Dependent (z): As conversões de um tipo Java String para o tipo de dados SQL Server subjacente dependem das seguintes condições: O driver envia o valor String para SQL Server e o SQL Server realiza conversões, se necessário. Se a propriedade de ligação sendStringParametersAsUnicode estiver definida como true e o tipo de dado subjacente do SQL Server for image, o SQL Server não permite converter nvarchar em image e lança uma SQLServerException. Se o sendStringParametersAsUnicode estiver definido como falso e o tipo de dado subjacente do SQL Server for image, o SQL Server permite converter varchar em image e não lança exceções.

O SQL Server realiza a maior parte das conversões do conjunto e transmite erros de volta para o driver JDBC quando surgem problemas. As conversões do lado do cliente são a exceção e são realizadas apenas no caso de valores de data, hora, carimbo temporal, Booleano e String .

Quando o tipo de dado da coluna SQL Server é XML, o valor dos dados deve ser um XML válido. Ao chamar métodos setObject(byte[], SQLXML), setObject(inputStream, SQLXML) ou setObject(Blob, SQLXML), o valor dos dados deve ser a representação hexadecimal da cadeia dos caracteres XML. Por exemplo:

<hello>world</hello> = 0x3C68656C6C6F3E776F726C643C2F68656C6C6F3E

Note que é necessária uma marca de ordem de bytes (BOM) se os caracteres XML estiverem em codificações específicas de caracteres.

Consulte também

Noções básicas sobre os tipos de dados do driver JDBC