libdb/lang/sql/jdbc/doc/SQLite/StringEncoder.html

391 lines
16 KiB
HTML
Raw Normal View History

2011-09-13 17:44:24 +00:00
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<!--NewPage-->
<HTML>
<HEAD>
<!-- Generated by javadoc (build 1.4.2_03) on Sat Apr 30 14:01:27 CEST 2011 -->
<TITLE>
StringEncoder (SQLite Java Wrapper)
</TITLE>
<META NAME="keywords" CONTENT="SQLite.StringEncoder class">
<LINK REL ="stylesheet" TYPE="text/css" HREF="../stylesheet.css" TITLE="Style">
<SCRIPT type="text/javascript">
function windowTitle()
{
parent.document.title="StringEncoder (SQLite Java Wrapper)";
}
</SCRIPT>
</HEAD>
<BODY BGCOLOR="white" onload="windowTitle();">
<!-- ========= START OF TOP NAVBAR ======= -->
<A NAME="navbar_top"><!-- --></A>
<A HREF="#skip-navbar_top" title="Skip navigation links"></A>
<TABLE BORDER="0" WIDTH="100%" CELLPADDING="1" CELLSPACING="0" SUMMARY="">
<TR>
<TD COLSPAN=3 BGCOLOR="#EEEEFF" CLASS="NavBarCell1">
<A NAME="navbar_top_firstrow"><!-- --></A>
<TABLE BORDER="0" CELLPADDING="0" CELLSPACING="3" SUMMARY="">
<TR ALIGN="center" VALIGN="top">
<TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="../overview-summary.html"><FONT CLASS="NavBarFont1"><B>Overview</B></FONT></A>&nbsp;</TD>
<TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="package-summary.html"><FONT CLASS="NavBarFont1"><B>Package</B></FONT></A>&nbsp;</TD>
<TD BGCOLOR="#FFFFFF" CLASS="NavBarCell1Rev"> &nbsp;<FONT CLASS="NavBarFont1Rev"><B>Class</B></FONT>&nbsp;</TD>
<TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="package-tree.html"><FONT CLASS="NavBarFont1"><B>Tree</B></FONT></A>&nbsp;</TD>
</TR>
</TABLE>
</TD>
<TD ALIGN="right" VALIGN="top" ROWSPAN=3><EM>
</EM>
</TD>
</TR>
<TR>
<TD BGCOLOR="white" CLASS="NavBarCell2"><FONT SIZE="-2">
&nbsp;<A HREF="../SQLite/Stmt.html" title="class in SQLite"><B>PREV CLASS</B></A>&nbsp;
&nbsp;<A HREF="../SQLite/TableResult.html" title="class in SQLite"><B>NEXT CLASS</B></A></FONT></TD>
<TD BGCOLOR="white" CLASS="NavBarCell2"><FONT SIZE="-2">
<A HREF="../index.html" target="_top"><B>FRAMES</B></A> &nbsp;
&nbsp;<A HREF="StringEncoder.html" target="_top"><B>NO FRAMES</B></A> &nbsp;
&nbsp;<SCRIPT type="text/javascript">
<!--
if(window==top) {
document.writeln('<A HREF="../allclasses-noframe.html"><B>All Classes</B></A>');
}
//-->
</SCRIPT>
<NOSCRIPT>
<A HREF="../allclasses-noframe.html"><B>All Classes</B></A>
</NOSCRIPT>
</FONT></TD>
</TR>
<TR>
<TD VALIGN="top" CLASS="NavBarCell3"><FONT SIZE="-2">
SUMMARY:&nbsp;NESTED&nbsp;|&nbsp;<A HREF="#field_summary">FIELD</A>&nbsp;|&nbsp;<A HREF="#constructor_summary">CONSTR</A>&nbsp;|&nbsp;<A HREF="#method_summary">METHOD</A></FONT></TD>
<TD VALIGN="top" CLASS="NavBarCell3"><FONT SIZE="-2">
DETAIL:&nbsp;<A HREF="#field_detail">FIELD</A>&nbsp;|&nbsp;<A HREF="#constructor_detail">CONSTR</A>&nbsp;|&nbsp;<A HREF="#method_detail">METHOD</A></FONT></TD>
</TR>
</TABLE>
<A NAME="skip-navbar_top"></A>
<!-- ========= END OF TOP NAVBAR ========= -->
<HR>
<!-- ======== START OF CLASS DATA ======== -->
<H2>
<FONT SIZE="-1">
SQLite</FONT>
<BR>
Class StringEncoder</H2>
<PRE>
<A HREF="http://java.sun.com/javase/6/docs/api/java/lang/Object.html" title="class or interface in java.lang">java.lang.Object</A>
<IMG SRC="../resources/inherit.gif" ALT="extended by"><B>SQLite.StringEncoder</B>
</PRE>
<HR>
<DL>
<DT>public class <B>StringEncoder</B><DT>extends <A HREF="http://java.sun.com/javase/6/docs/api/java/lang/Object.html" title="class or interface in java.lang">Object</A></DL>
<P>
String encoder/decoder for SQLite.
This module was kindly donated by Eric van der Maarel of Nedap N.V.
This encoder was implemented based on an original idea from an anonymous
author in the source code of the SQLite distribution.
I feel obliged to provide a quote from the original C-source code:
"The author disclaims copyright to this source code. In place of
a legal notice, here is a blessing:
May you do good and not evil.
May you find forgiveness for yourself and forgive others.
May you share freely, never taking more than you give."
<P>
<P>
<HR>
<P>
<!-- ======== NESTED CLASS SUMMARY ======== -->
<!-- =========== FIELD SUMMARY =========== -->
<A NAME="field_summary"><!-- --></A>
<TABLE BORDER="1" WIDTH="100%" CELLPADDING="3" CELLSPACING="0" SUMMARY="">
<TR BGCOLOR="#CCCCFF" CLASS="TableHeadingColor">
<TD COLSPAN=2><FONT SIZE="+2">
<B>Field Summary</B></FONT></TD>
</TR>
<TR BGCOLOR="white" CLASS="TableRowColor">
<TD ALIGN="right" VALIGN="top" WIDTH="1%"><FONT SIZE="-1">
<CODE>(package private) static&nbsp;char[]</CODE></FONT></TD>
<TD><CODE><B><A HREF="../SQLite/StringEncoder.html#xdigits">xdigits</A></B></CODE>
<BR>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</TD>
</TR>
</TABLE>
&nbsp;
<!-- ======== CONSTRUCTOR SUMMARY ======== -->
<A NAME="constructor_summary"><!-- --></A>
<TABLE BORDER="1" WIDTH="100%" CELLPADDING="3" CELLSPACING="0" SUMMARY="">
<TR BGCOLOR="#CCCCFF" CLASS="TableHeadingColor">
<TD COLSPAN=2><FONT SIZE="+2">
<B>Constructor Summary</B></FONT></TD>
</TR>
<TR BGCOLOR="white" CLASS="TableRowColor">
<TD><CODE><B><A HREF="../SQLite/StringEncoder.html#StringEncoder()">StringEncoder</A></B>()</CODE>
<BR>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</TD>
</TR>
</TABLE>
&nbsp;
<!-- ========== METHOD SUMMARY =========== -->
<A NAME="method_summary"><!-- --></A>
<TABLE BORDER="1" WIDTH="100%" CELLPADDING="3" CELLSPACING="0" SUMMARY="">
<TR BGCOLOR="#CCCCFF" CLASS="TableHeadingColor">
<TD COLSPAN=2><FONT SIZE="+2">
<B>Method Summary</B></FONT></TD>
</TR>
<TR BGCOLOR="white" CLASS="TableRowColor">
<TD ALIGN="right" VALIGN="top" WIDTH="1%"><FONT SIZE="-1">
<CODE>private static&nbsp;byte[]</CODE></FONT></TD>
<TD><CODE><B><A HREF="../SQLite/StringEncoder.html#byteCopy(byte[], int, int, byte[])">byteCopy</A></B>(byte[]&nbsp;source,
int&nbsp;offset,
int&nbsp;count,
byte[]&nbsp;target)</CODE>
<BR>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Copies count elements from source, starting at element with
index offset, to the given target.</TD>
</TR>
<TR BGCOLOR="white" CLASS="TableRowColor">
<TD ALIGN="right" VALIGN="top" WIDTH="1%"><FONT SIZE="-1">
<CODE>static&nbsp;byte[]</CODE></FONT></TD>
<TD><CODE><B><A HREF="../SQLite/StringEncoder.html#decode(java.lang.String)">decode</A></B>(<A HREF="http://java.sun.com/javase/6/docs/api/java/lang/String.html" title="class or interface in java.lang">String</A>&nbsp;s)</CODE>
<BR>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Decodes the given string that is assumed to be a valid encoding
of a byte array.</TD>
</TR>
<TR BGCOLOR="white" CLASS="TableRowColor">
<TD ALIGN="right" VALIGN="top" WIDTH="1%"><FONT SIZE="-1">
<CODE>static&nbsp;<A HREF="http://java.sun.com/javase/6/docs/api/java/lang/String.html" title="class or interface in java.lang">String</A></CODE></FONT></TD>
<TD><CODE><B><A HREF="../SQLite/StringEncoder.html#encode(byte[])">encode</A></B>(byte[]&nbsp;a)</CODE>
<BR>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Encodes the given byte array into a string that can be used by
the SQLite database.</TD>
</TR>
<TR BGCOLOR="white" CLASS="TableRowColor">
<TD ALIGN="right" VALIGN="top" WIDTH="1%"><FONT SIZE="-1">
<CODE>static&nbsp;<A HREF="http://java.sun.com/javase/6/docs/api/java/lang/String.html" title="class or interface in java.lang">String</A></CODE></FONT></TD>
<TD><CODE><B><A HREF="../SQLite/StringEncoder.html#encodeX(byte[])">encodeX</A></B>(byte[]&nbsp;a)</CODE>
<BR>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Encodes the given byte array into SQLite3 blob notation, ie X'..'</TD>
</TR>
</TABLE>
&nbsp;<A NAME="methods_inherited_from_class_java.lang.Object"><!-- --></A>
<TABLE BORDER="1" WIDTH="100%" CELLPADDING="3" CELLSPACING="0" SUMMARY="">
<TR BGCOLOR="#EEEEFF" CLASS="TableSubHeadingColor">
<TD><B>Methods inherited from class java.lang.<A HREF="http://java.sun.com/javase/6/docs/api/java/lang/Object.html" title="class or interface in java.lang">Object</A></B></TD>
</TR>
<TR BGCOLOR="white" CLASS="TableRowColor">
<TD><CODE><A HREF="http://java.sun.com/javase/6/docs/api/java/lang/Object.html#clone()" title="class or interface in java.lang">clone</A>, <A HREF="http://java.sun.com/javase/6/docs/api/java/lang/Object.html#equals(java.lang.Object)" title="class or interface in java.lang">equals</A>, <A HREF="http://java.sun.com/javase/6/docs/api/java/lang/Object.html#finalize()" title="class or interface in java.lang">finalize</A>, <A HREF="http://java.sun.com/javase/6/docs/api/java/lang/Object.html#getClass()" title="class or interface in java.lang">getClass</A>, <A HREF="http://java.sun.com/javase/6/docs/api/java/lang/Object.html#hashCode()" title="class or interface in java.lang">hashCode</A>, <A HREF="http://java.sun.com/javase/6/docs/api/java/lang/Object.html#notify()" title="class or interface in java.lang">notify</A>, <A HREF="http://java.sun.com/javase/6/docs/api/java/lang/Object.html#notifyAll()" title="class or interface in java.lang">notifyAll</A>, <A HREF="http://java.sun.com/javase/6/docs/api/java/lang/Object.html#toString()" title="class or interface in java.lang">toString</A>, <A HREF="http://java.sun.com/javase/6/docs/api/java/lang/Object.html#wait()" title="class or interface in java.lang">wait</A>, <A HREF="http://java.sun.com/javase/6/docs/api/java/lang/Object.html#wait(long)" title="class or interface in java.lang">wait</A>, <A HREF="http://java.sun.com/javase/6/docs/api/java/lang/Object.html#wait(long, int)" title="class or interface in java.lang">wait</A></CODE></TD>
</TR>
</TABLE>
&nbsp;
<P>
<!-- ============ FIELD DETAIL =========== -->
<A NAME="field_detail"><!-- --></A>
<TABLE BORDER="1" WIDTH="100%" CELLPADDING="3" CELLSPACING="0" SUMMARY="">
<TR BGCOLOR="#CCCCFF" CLASS="TableHeadingColor">
<TD COLSPAN=1><FONT SIZE="+2">
<B>Field Detail</B></FONT></TD>
</TR>
</TABLE>
<A NAME="xdigits"><!-- --></A><H3>
xdigits</H3>
<PRE>
static final char[] <B>xdigits</B></PRE>
<DL>
<DL>
</DL>
</DL>
<!-- ========= CONSTRUCTOR DETAIL ======== -->
<A NAME="constructor_detail"><!-- --></A>
<TABLE BORDER="1" WIDTH="100%" CELLPADDING="3" CELLSPACING="0" SUMMARY="">
<TR BGCOLOR="#CCCCFF" CLASS="TableHeadingColor">
<TD COLSPAN=1><FONT SIZE="+2">
<B>Constructor Detail</B></FONT></TD>
</TR>
</TABLE>
<A NAME="StringEncoder()"><!-- --></A><H3>
StringEncoder</H3>
<PRE>
public <B>StringEncoder</B>()</PRE>
<DL>
</DL>
<!-- ============ METHOD DETAIL ========== -->
<A NAME="method_detail"><!-- --></A>
<TABLE BORDER="1" WIDTH="100%" CELLPADDING="3" CELLSPACING="0" SUMMARY="">
<TR BGCOLOR="#CCCCFF" CLASS="TableHeadingColor">
<TD COLSPAN=1><FONT SIZE="+2">
<B>Method Detail</B></FONT></TD>
</TR>
</TABLE>
<A NAME="byteCopy(byte[], int, int, byte[])"><!-- --></A><H3>
byteCopy</H3>
<PRE>
private static byte[] <B>byteCopy</B>(byte[]&nbsp;source,
int&nbsp;offset,
int&nbsp;count,
byte[]&nbsp;target)</PRE>
<DL>
<DD>Copies count elements from source, starting at element with
index offset, to the given target.
<P>
<DD><DL>
<DT><B>Parameters:</B><DD><CODE>source</CODE> - the source.<DD><CODE>offset</CODE> - the offset.<DD><CODE>count</CODE> - the number of elements to be copied.<DD><CODE>target</CODE> - the target to be returned.
<DT><B>Returns:</B><DD>the target being copied to.</DL>
</DD>
</DL>
<HR>
<A NAME="decode(java.lang.String)"><!-- --></A><H3>
decode</H3>
<PRE>
public static byte[] <B>decode</B>(<A HREF="http://java.sun.com/javase/6/docs/api/java/lang/String.html" title="class or interface in java.lang">String</A>&nbsp;s)</PRE>
<DL>
<DD>Decodes the given string that is assumed to be a valid encoding
of a byte array. Typically the given string is generated by
this class' <code>encode</code> method.
<P>
<DD><DL>
<DT><B>Parameters:</B><DD><CODE>s</CODE> - the given string encoding.
<DT><B>Returns:</B><DD>the byte array obtained from the decoding.
<DT><B>Throws:</B>
<DD><CODE><A HREF="http://java.sun.com/javase/6/docs/api/java/lang/IllegalArgumentException.html" title="class or interface in java.lang">IllegalArgumentException</A></CODE> - when the string given is not
a valid encoded string for this encoder.</DL>
</DD>
</DL>
<HR>
<A NAME="encode(byte[])"><!-- --></A><H3>
encode</H3>
<PRE>
public static <A HREF="http://java.sun.com/javase/6/docs/api/java/lang/String.html" title="class or interface in java.lang">String</A> <B>encode</B>(byte[]&nbsp;a)</PRE>
<DL>
<DD>Encodes the given byte array into a string that can be used by
the SQLite database. The database cannot handle null (0x00) and
the character '\'' (0x27). The encoding consists of escaping
these characters with a reserved character (0x01). The escaping
is applied after determining and applying a shift that minimizes
the number of escapes required.
With this encoding the data of original size n is increased to a
maximum of 1+(n*257)/254.
For sufficiently large n the overhead is thus less than 1.2%.
<P>
<DD><DL>
<DT><B>Parameters:</B><DD><CODE>a</CODE> - the byte array to be encoded. A null reference is handled as
an empty array.
<DT><B>Returns:</B><DD>the encoded bytes as a string. When an empty array is
provided a string of length 1 is returned, the value of
which is bogus.
When decoded with this class' <code>decode</code> method
a string of size 1 will return an empty byte array.</DL>
</DD>
</DL>
<HR>
<A NAME="encodeX(byte[])"><!-- --></A><H3>
encodeX</H3>
<PRE>
public static <A HREF="http://java.sun.com/javase/6/docs/api/java/lang/String.html" title="class or interface in java.lang">String</A> <B>encodeX</B>(byte[]&nbsp;a)</PRE>
<DL>
<DD>Encodes the given byte array into SQLite3 blob notation, ie X'..'
<P>
<DD><DL>
<DT><B>Parameters:</B><DD><CODE>a</CODE> - the byte array to be encoded. A null reference is handled as
an empty array.
<DT><B>Returns:</B><DD>the encoded bytes as a string.</DL>
</DD>
</DL>
<!-- ========= END OF CLASS DATA ========= -->
<HR>
<!-- ======= START OF BOTTOM NAVBAR ====== -->
<A NAME="navbar_bottom"><!-- --></A>
<A HREF="#skip-navbar_bottom" title="Skip navigation links"></A>
<TABLE BORDER="0" WIDTH="100%" CELLPADDING="1" CELLSPACING="0" SUMMARY="">
<TR>
<TD COLSPAN=3 BGCOLOR="#EEEEFF" CLASS="NavBarCell1">
<A NAME="navbar_bottom_firstrow"><!-- --></A>
<TABLE BORDER="0" CELLPADDING="0" CELLSPACING="3" SUMMARY="">
<TR ALIGN="center" VALIGN="top">
<TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="../overview-summary.html"><FONT CLASS="NavBarFont1"><B>Overview</B></FONT></A>&nbsp;</TD>
<TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="package-summary.html"><FONT CLASS="NavBarFont1"><B>Package</B></FONT></A>&nbsp;</TD>
<TD BGCOLOR="#FFFFFF" CLASS="NavBarCell1Rev"> &nbsp;<FONT CLASS="NavBarFont1Rev"><B>Class</B></FONT>&nbsp;</TD>
<TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="package-tree.html"><FONT CLASS="NavBarFont1"><B>Tree</B></FONT></A>&nbsp;</TD>
</TR>
</TABLE>
</TD>
<TD ALIGN="right" VALIGN="top" ROWSPAN=3><EM>
</EM>
</TD>
</TR>
<TR>
<TD BGCOLOR="white" CLASS="NavBarCell2"><FONT SIZE="-2">
&nbsp;<A HREF="../SQLite/Stmt.html" title="class in SQLite"><B>PREV CLASS</B></A>&nbsp;
&nbsp;<A HREF="../SQLite/TableResult.html" title="class in SQLite"><B>NEXT CLASS</B></A></FONT></TD>
<TD BGCOLOR="white" CLASS="NavBarCell2"><FONT SIZE="-2">
<A HREF="../index.html" target="_top"><B>FRAMES</B></A> &nbsp;
&nbsp;<A HREF="StringEncoder.html" target="_top"><B>NO FRAMES</B></A> &nbsp;
&nbsp;<SCRIPT type="text/javascript">
<!--
if(window==top) {
document.writeln('<A HREF="../allclasses-noframe.html"><B>All Classes</B></A>');
}
//-->
</SCRIPT>
<NOSCRIPT>
<A HREF="../allclasses-noframe.html"><B>All Classes</B></A>
</NOSCRIPT>
</FONT></TD>
</TR>
<TR>
<TD VALIGN="top" CLASS="NavBarCell3"><FONT SIZE="-2">
SUMMARY:&nbsp;NESTED&nbsp;|&nbsp;<A HREF="#field_summary">FIELD</A>&nbsp;|&nbsp;<A HREF="#constructor_summary">CONSTR</A>&nbsp;|&nbsp;<A HREF="#method_summary">METHOD</A></FONT></TD>
<TD VALIGN="top" CLASS="NavBarCell3"><FONT SIZE="-2">
DETAIL:&nbsp;<A HREF="#field_detail">FIELD</A>&nbsp;|&nbsp;<A HREF="#constructor_detail">CONSTR</A>&nbsp;|&nbsp;<A HREF="#method_detail">METHOD</A></FONT></TD>
</TR>
</TABLE>
<A NAME="skip-navbar_bottom"></A>
<!-- ======== END OF BOTTOM NAVBAR ======= -->
<HR>
<small>Contact: <a HREF="mailto:chw@ch-werner.de">Christian Werner</a></small>
</BODY>
</HTML>