db-derby-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From scotsmat...@apache.org
Subject svn commit: r545561 - in /db/derby/docs/trunk/src: devguide/cdevcollation.dita devguide/cdevdvlp51654.dita devguide/derbydev.ditamap devguide/tdevdvlpcollation.dita ref/refderby.ditamap ref/rrefattrib56769.dita ref/rrefattribcollation.dita
Date Fri, 08 Jun 2007 17:02:25 GMT
Author: scotsmatrix
Date: Fri Jun  8 10:02:23 2007
New Revision: 545561

URL: http://svn.apache.org/viewvc?view=rev&rev=545561
Log:
DERBY-2377: Adds documentation for territory-based collation. Patch derby2377_2.diff as contributed
by me.

Added:
    db/derby/docs/trunk/src/devguide/cdevcollation.dita   (with props)
    db/derby/docs/trunk/src/devguide/tdevdvlpcollation.dita   (with props)
    db/derby/docs/trunk/src/ref/rrefattribcollation.dita   (with props)
Modified:
    db/derby/docs/trunk/src/devguide/cdevdvlp51654.dita
    db/derby/docs/trunk/src/devguide/derbydev.ditamap
    db/derby/docs/trunk/src/ref/refderby.ditamap
    db/derby/docs/trunk/src/ref/rrefattrib56769.dita

Added: db/derby/docs/trunk/src/devguide/cdevcollation.dita
URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/devguide/cdevcollation.dita?view=auto&rev=545561
==============================================================================
--- db/derby/docs/trunk/src/devguide/cdevcollation.dita (added)
+++ db/derby/docs/trunk/src/devguide/cdevcollation.dita Fri Jun  8 10:02:23 2007
@@ -0,0 +1,130 @@
+<?xml version="1.0" encoding="utf-8"?>
+
+<!DOCTYPE concept PUBLIC "-//OASIS//DTD DITA Concept//EN"
+ "../dtd/concept.dtd">
+<!-- 
+Licensed to the Apache Software Foundation (ASF) under one or more
+contributor license agreements.  See the NOTICE file distributed with
+this work for additional information regarding copyright ownership.
+The ASF licenses this file to You under the Apache License, Version 2.0
+(the "License"); you may not use this file except in compliance with
+the License.  You may obtain a copy of the License at      
+
+   http://www.apache.org/licenses/LICENSE-2.0  
+
+Unless required by applicable law or agreed to in writing, software  
+distributed under the License is distributed on an "AS IS" BASIS,  
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.  
+See the License for the specific language governing permissions and  
+limitations under the License.
+-->
+<concept id="cdevcollation" xml:lang="en-us">
+<title>Character-based collation in <ph conref="../conrefs.dita#prod/productshortname"></ph></title>
+<shortdesc>A character set is a set of symbols and encodings. Character data
+types are represented as Unicode 2.0 sequences in <ph conref="../conrefs.dita#prod/productshortname"></ph>.
</shortdesc>
+<prolog><metadata>
+<keywords><indexterm>collation<indexterm>overview</indexterm></indexterm>
+<indexterm></indexterm></keywords>
+</metadata></prolog>
+<conbody>
+<section><title>How collation works in <ph conref="../conrefs.dita#prod/productshortname"></ph></title><p><ph
+conref="../conrefs.dita#prod/productshortname"></ph> supports a wide range
+of character sets and encodes all of the character sets by using the Unicode
+support provided by the java.lang.Character  class in the Java Virtual Machine
+(JVM) in which the <ph conref="../conrefs.dita#prod/productshortname"></ph> database
+runs. See the Java API documentation for the java.lang.Character class for
+the exact level of Unicode Standard that is supported.</p><p>A collation is
+a set of rules for comparing characters in a character set.  In <ph conref="../conrefs.dita#prod/productshortname"></ph>
the
+collation rules affect comparisons of the CHAR and VARCHAR data  types. Collation
+rules also affect how the LIKE Boolean operator processes the CHAR, VARCHAR,
+CLOB, and LONG VARCHAR data types.</p><p>The default <ph conref="../conrefs.dita#prod/productshortname"></ph>
collation
+rule is based on the binary Unicode values of the characters. So a character
+is greater than (&lt;), equal to (=), or less than (>) another character based
+on the numeric comparison of the Unicode values. This rule allows for very
+efficient comparisons of character strings.</p><p><ph conref="../conrefs.dita#prod/productshortname"></ph>
also
+supports the ability to define collation rules that are appropriate to a territory,
+and is referred to as <i><term>territory-based collation</term></i>.
 You
+can specifically set the territory of a database when you create the database.
+If you do not specify a territory, <ph conref="../conrefs.dita#prod/productshortname"></ph>
uses
+the default territory of the JVM in which the database is created. Each JVM
+can support many territories that are independent from the default territory
+for the JVM. Collation support for these additional territories is provided
+through the<codeph> java.text.RuleBasedCollator</codeph> class and the set
+of rules for these territories. Refer to the JVM specification for details
+of how these rules are used to provide territory specific collation. <ph conref="../conrefs.dita#prod/productshortname"></ph>
currently
+supports only running those rules that can be loaded dynamically from the
+running JVM based on the territory attribute. Overrides to these rules by
+the user are not supported. </p><p>Territory-based collation does add extra
+processing overhead to all character-based comparison operations.</p><p>When
+you create a <ph conref="../conrefs.dita#prod/productshortname"></ph> database,
+the attributes that you set determine the collation that is used with all
+of character data in the database. For example: <table><title>The create database
+attributes that control collation</title>
+<tgroup cols="2"><colspec colname="col1"/><colspec colname="col2"/>
+<thead>
+<row valign="bottom">
+<entry colname="col1">Example create commands</entry>
+<entry colname="col2">Collation is driven by</entry>
+</row>
+</thead>
+<tbody>
+<row>
+<entry colname="col1">jdbc:derby:abcDB;create=true</entry>
+<entry colname="col2">Unicode codepoint collation (UCS_BASIC), which is the
+default collation for <ph conref="../conrefs.dita#prod/productshortname"></ph>
databases. </entry>
+</row>
+<row>
+<entry colname="col1">jdbc:derby:abcDB;create=true;territory=es_MX</entry>
+<entry colname="col2">Unicode codepoint collation (UCS_BASIC). The <codeph>collation</codeph>
attribute
+is not set.</entry>
+</row>
+<row>
+<entry colname="col1">jdbc:derby:abcDB;create=true;collation=TERRITORY_BASED </entry>
+<entry colname="col2">The territory of the JVM, since the <codeph>territory</codeph>
attribute
+is not set. <note type="tip">To determine the territory of the JVM, run <codeph>Locale.getDefault()</codeph>.</note></entry>
+</row>
+<row>
+<entry colname="col1">jdbc:derby:abcDB;create=true;territory=es_MX;collation=TERRITORY_BASED
</entry>
+<entry colname="col2">The <codeph>territory</codeph> attribute.</entry>
+</row>
+</tbody>
+</tgroup>
+</table></p><p>The territory-based collation in <ph conref="../conrefs.dita#prod/productshortname"></ph>
affects
+how the CHAR and VARCHAR data types are compared. Specifying territory-based
+collation also impacts how the LIKE Boolean operator processes CHAR, VARCHAR,
+CLOB, and LONG VARCHAR data. <ph conref="../conrefs.dita#prod/productshortname"></ph>
supports
+the territories that Java supports.</p></section>
+<section><title>Collation examples</title><p>With Unicode codepoint
collation
+(UCS_BASIC), the numerical values of the Unicode encoding of the characters
+is used directly for ordering. For example, the FRUIT table contains the NAME
+column that uses the VARCHAR(20) data type. The contents of the NAME column
+are:<sl>
+<sli>orange</sli>
+<sli>apple</sli>
+<sli>Banana</sli>
+<sli>Pineapple</sli>
+<sli>Grape</sli>
+</sl></p><p>UCS_BASIC collation sorts all lower case letters before upper
+case letters. The statement <codeph>SELECT * FROM FRUIT ORDER BY NAME</codeph>
returns: <sl>
+<sli>apple</sli>
+<sli>orange</sli>
+<sli>Banana</sli>
+<sli>Grape</sli>
+<sli>Pineapple</sli>
+</sl></p><p>If the database is created with the territory attribute set
to
+en_US (English language, United States country code), and the collation attribute
+set to TERRITORY_BASED , the results of the statement <codeph>SELECT * FROM
+FRUIT ORDER BY NAME</codeph> returns: <sl>
+<sli>apple</sli>
+<sli>Banana</sli>
+<sli>Grape</sli>
+<sli>orange</sli>
+<sli>Pineapple</sli>
+</sl></p><p>The collation set for the database also impacts comparison
operators
+on character data types. For example, the statement <codeph>SELECT * FROM
+FRUIT WHERE NAME > Banana</codeph> returns: <lines>      UCS_BASIC collation
      Territory-based collation
+                Grape                                Grape
+                Pineapple                           orange
+                                                         Pineapple</lines></p>
</section>
+</conbody>
+</concept>

Propchange: db/derby/docs/trunk/src/devguide/cdevcollation.dita
------------------------------------------------------------------------------
    svn:eol-style = native

Modified: db/derby/docs/trunk/src/devguide/cdevdvlp51654.dita
URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/devguide/cdevdvlp51654.dita?view=diff&rev=545561&r1=545560&r2=545561
==============================================================================
--- db/derby/docs/trunk/src/devguide/cdevdvlp51654.dita (original)
+++ db/derby/docs/trunk/src/devguide/cdevdvlp51654.dita Fri Jun  8 10:02:23 2007
@@ -34,12 +34,11 @@
 <p>You can also set these attributes by passing a <i>Properties</i> object
 along with a connection URL to <codeph><i>DriverManager.getConnection</i></codeph>
when
 obtaining a connection; see "Specifying Attributes in a Properties Object".</p>
-<p>All attributes are optional. For detailed information about the connection
-URL syntax and attributes, see "<ph conref="../conrefs.dita#prod/productshortname"></ph>
Database
-Connection URL Syntax"in the <cite><ph conref="../conrefs.dita#pub/citref"></ph></cite>.</p>
+<p>All attributes are optional. </p>
 <p>You can specify the following attributes:</p>
 <ul>
 <li><i>bootPassword=key</i>  </li>
+<li><i>collation=collationAttribute</i>  </li>
 <li><i>create=true</i>  </li>
 <li><i>databaseName=nameofDatabase</i>  </li>
 <li><i>dataEncryption=true</i>  </li>
@@ -54,5 +53,8 @@
 <li><i>shutdown=true</i>  </li>
 <li><i>user=userName</i>  </li>
 </ul>
+<p>For detailed information about the connection URL syntax and attributes,
+see "<ph conref="../conrefs.dita#prod/productshortname"></ph> Database Connection
+URL Syntax" in the <cite><ph conref="../conrefs.dita#pub/citref"></ph></cite>.</p>
 </conbody>
 </concept>

Modified: db/derby/docs/trunk/src/devguide/derbydev.ditamap
URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/devguide/derbydev.ditamap?view=diff&rev=545561&r1=545560&r2=545561
==============================================================================
--- db/derby/docs/trunk/src/devguide/derbydev.ditamap (original)
+++ db/derby/docs/trunk/src/devguide/derbydev.ditamap Fri Jun  8 10:02:23 2007
@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="utf-8"?>
- 
+
 <!DOCTYPE map PUBLIC "-//OASIS//DTD DITA Map//EN"
  "map.dtd">
 <!-- 
@@ -1960,6 +1960,8 @@
 </topicref>
 <topicref href="tdevdvlp12233.dita" navtitle="Providing a user name and password">
 </topicref>
+<topicref href="tdevdvlpcollation.dita" navtitle="Creating a database with territory-based
collation">
+</topicref>
 <topicref href="tdevdvlp14496.dita" navtitle="Encrypting a database when you create it">
 </topicref>
 <topicref href="tdevdvlpcreateencryptdbextkey.dita" navtitle="Creating an encrypted database
with an external key">
@@ -2335,6 +2337,8 @@
 </topicref>
 <topicref href="cdevin55108.dita" navtitle="Other components"></topicref>
 <topicref href="cdevin38113.dita" navtitle="Messages libraries"></topicref>
+</topicref>
+<topicref href="cdevcollation.dita" navtitle="Character-based collation in  Derby">
 </topicref>
 <topicref href="cdevstandards806118.dita" navtitle="Derby and standards">
 <topicref href="cdevstandardsxml.dita" navtitle="XML data types and operators">

Added: db/derby/docs/trunk/src/devguide/tdevdvlpcollation.dita
URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/devguide/tdevdvlpcollation.dita?view=auto&rev=545561
==============================================================================
--- db/derby/docs/trunk/src/devguide/tdevdvlpcollation.dita (added)
+++ db/derby/docs/trunk/src/devguide/tdevdvlpcollation.dita Fri Jun  8 10:02:23 2007
@@ -0,0 +1,45 @@
+<?xml version="1.0" encoding="utf-8"?>
+
+<!DOCTYPE task PUBLIC "-//OASIS//DTD DITA Task//EN"
+ "../dtd/task.dtd">
+<!-- 
+Licensed to the Apache Software Foundation (ASF) under one or more
+contributor license agreements.  See the NOTICE file distributed with
+this work for additional information regarding copyright ownership.
+The ASF licenses this file to You under the Apache License, Version 2.0
+(the "License"); you may not use this file except in compliance with
+the License.  You may obtain a copy of the License at      
+
+   http://www.apache.org/licenses/LICENSE-2.0  
+
+Unless required by applicable law or agreed to in writing, software  
+distributed under the License is distributed on an "AS IS" BASIS,  
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.  
+See the License for the specific language governing permissions and  
+limitations under the License.
+-->
+<task id="tdevdvlpcollation" xml:lang="en-us">
+<title>Creating a database with territory-based collation</title>
+<shortdesc>By default, <ph conref="../conrefs.dita#prod/productshortname"></ph>
uses
+Unicode codepoint collation. However, you can specify territory-based collation
+when you create the database.</shortdesc>
+<prolog><metadata>
+<keywords><indexterm>database attributes <indexterm>territory-based collation</indexterm></indexterm>
+<indexterm>collation <indexterm>territory-based</indexterm></indexterm></keywords>
+</metadata></prolog>
+<taskbody>
+<context>.<p>You can use the <codeph>collation</codeph> and <codeph>territory</codeph>
attributes
+to specify territory-based collation. This type of collation applies only
+to user-defined tables. The system tables use the Unicode codepoint collation. </p><note
+type="restriction">The <codeph>collation</codeph> attribute can be specified
+only when you create a database. You cannot specify this attribute on an existing
+database or when you upgrade a database.</note><p>To create a database with
+territory-based collation:</p></context>
+<steps>
+<step><cmd>Specify the language and country codes for the <codeph>territory</codeph>
attribute,
+and the TERRITORY_BASED value for the <codeph>collation</codeph> attribute
+when you create the database.</cmd><stepxmp><p>For example:</p><codeblock>jdbc:derby:MexicanDB;create=true;territory=es_MX;collation=TERRITORY_BASED
</codeblock
+></stepxmp></step>
+</steps>
+</taskbody>
+</task>

Propchange: db/derby/docs/trunk/src/devguide/tdevdvlpcollation.dita
------------------------------------------------------------------------------
    svn:eol-style = native

Modified: db/derby/docs/trunk/src/ref/refderby.ditamap
URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/ref/refderby.ditamap?view=diff&rev=545561&r1=545560&r2=545561
==============================================================================
--- db/derby/docs/trunk/src/ref/refderby.ditamap (original)
+++ db/derby/docs/trunk/src/ref/refderby.ditamap Fri Jun  8 10:02:23 2007
@@ -567,6 +567,8 @@
 <topicref href="rrefattrib24612.dita" navtitle="Setting attributes for the database connection
URL ">
 <topicref href="rrefattrib42100.dita" navtitle="bootPassword=key attribute">
 </topicref>
+<topicref href="rrefattribcollation.dita" navtitle="collation=collation attribute">
+</topicref>
 <topicref href="rrefattrib26867.dita" navtitle="create=true attribute"></topicref>
 <topicref href="rrefcreatefrom.dita" navtitle="createFrom=path attribute">
 </topicref>

Modified: db/derby/docs/trunk/src/ref/rrefattrib56769.dita
URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/ref/rrefattrib56769.dita?view=diff&rev=545561&r1=545560&r2=545561
==============================================================================
--- db/derby/docs/trunk/src/ref/rrefattrib56769.dita (original)
+++ db/derby/docs/trunk/src/ref/rrefattrib56769.dita Fri Jun  8 10:02:23 2007
@@ -1,4 +1,7 @@
 <?xml version="1.0" encoding="utf-8"?>
+
+<!DOCTYPE reference PUBLIC "-//OASIS//DTD DITA Reference//EN"
+ "../dtd/reference.dtd">
 <!-- 
 Licensed to the Apache Software Foundation (ASF) under one or more
 contributor license agreements.  See the NOTICE file distributed with
@@ -15,9 +18,6 @@
 See the License for the specific language governing permissions and  
 limitations under the License.
 -->
-
-<!DOCTYPE reference PUBLIC "-//OASIS//DTD DITA Reference//EN"
- "../dtd/reference.dtd">
 <reference id="rrefattrib56769" xml:lang="en-us">
 <title>territory=ll_CC attribute</title>
 <prolog><metadata>
@@ -33,8 +33,8 @@
 for that database. The default system territory is found using <i>java.util.Locale.getDefault()</i>.</p>
<p>Specify
 a territory in the form <i>ll_CC</i>, where <i>ll</i> is the two-letter
language
 code, and <i>CC</i> is the two-letter country code. </p> <p>Language
codes
-consist of a pair of lowercase letters that conform to ISO-639.   <table
-frame="all"><title>Sample Language Codes</title>
+consist of a pair of lowercase letters that conform to ISO-639.   <table frame="all">
+<title>Sample Language Codes</title>
 <tgroup cols="2" colsep="1" rowsep="1"><colspec colname="1" colnum="1" colwidth="50*"/>
 <colspec colname="2" colnum="2" colwidth="50*"/>
 <thead>
@@ -100,9 +100,10 @@
 </table></p> <p>A copy of ISO-3166 can be found at <xref format="html"
href="http://www.chemie.fu-berlin.de/diverse/doc/ISO_3166.html"
 scope="external"><i>http://www.chemie.fu-berlin.de/diverse/doc/ISO_3166.html</i></xref>.</p>
</section>
 <section><title>Combining with other attributes</title> <p>The <i>territory</i>
attribute
-is used only when creating a database.</p> </section>
-<example> <p>In the following example, the new database has a territory of
-Spanish language and Mexican nationality.</p> <codeblock><b>jdbc:derby:MexicanDB;create=true;territory=es_MX</b></codeblock>
</example>
+is used only when creating a database.</p><p>In the following example, the
+new database has a territory of Spanish language and Mexican nationality.</p> <codeblock><b>jdbc:derby:MexicanDB;create=true;territory=es_MX</b></codeblock
+><p>You can use the <xref href="rrefattribcollation.dita#rrefattribcollation"><codeph>collation</codeph>
attribute</xref> with
+the <codeph>territory</codeph> attribute to specify that collation is based
+on the territory instead of based on Unicode codepoint collation,</p></section>
 </refbody>
 </reference>
-

Added: db/derby/docs/trunk/src/ref/rrefattribcollation.dita
URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/ref/rrefattribcollation.dita?view=auto&rev=545561
==============================================================================
--- db/derby/docs/trunk/src/ref/rrefattribcollation.dita (added)
+++ db/derby/docs/trunk/src/ref/rrefattribcollation.dita Fri Jun  8 10:02:23 2007
@@ -0,0 +1,56 @@
+<?xml version="1.0" encoding="utf-8"?>
+
+<!DOCTYPE reference PUBLIC "-//OASIS//DTD DITA Reference//EN"
+ "../dtd/reference.dtd">
+<!-- 
+Licensed to the Apache Software Foundation (ASF) under one or more
+contributor license agreements.  See the NOTICE file distributed with
+this work for additional information regarding copyright ownership.
+The ASF licenses this file to You under the Apache License, Version 2.0
+(the "License"); you may not use this file except in compliance with
+the License.  You may obtain a copy of the License at      
+
+http://www.apache.org/licenses/LICENSE-2.0  
+
+Unless required by applicable law or agreed to in writing, software  
+distributed under the License is distributed on an "AS IS" BASIS,  
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.  
+See the License for the specific language governing permissions and  
+limitations under the License.
+-->
+<reference id="rrefattribcollation" xml:lang="en-us">
+<title>collation=collation attribute</title>
+<prolog><metadata>
+<keywords><indexterm>collation<indexterm>database attribute</indexterm></indexterm>
+<indexterm>database attribute<indexterm>collation</indexterm></indexterm>
+<indexterm>TERRITORY_BASED <indexterm>collation attribute</indexterm></indexterm>
+</keywords>
+</metadata></prolog>
+<refbody>
+<section><title>Function</title><p>The <codeph>collation</codeph>
attribute
+is an optional attribute that specifies whether collation is based on the
+territory specified for the database or Unicode codepoint collation. The valid
+values for the <codeph>collation</codeph> attribute are: TERRITORY_BASED and
+UCS_BASIC. The default collation is Unicode codepoint collation (UCS_BASIC).</p><note
+type="restriction">The <codeph>collation</codeph> attribute can be specified
+only when you create a database. You cannot specify this attribute on an existing
+database or when you upgrade a database.</note><p>If you include the <codeph>collation</codeph>
attribute
+with the value TERRITORY_BASED when you create the <ph conref="../conrefs.dita#prod/productshortname"></ph>
database,
+the collation is based on the language and country codes that you specify
+with the <codeph>territory</codeph> attribute.</p><p>If you do not
specify
+the <codeph>territory</codeph> attribute when you create the database, <ph
+conref="../conrefs.dita#prod/productshortname"></ph> uses the <codeph>java.util.Locale.getDefault</codeph>
method
+to determine the current value of the default locale for this instance of
+the Java Virtual Machine (JVM).</p><note>The <codeph>collation</codeph>
attribute
+applies only to user-defined tables. The system tables use the Unicode codepoint
+collation.</note></section>
+<example><title>Example</title><p>The following example shows the
URL to create
+the <codeph>MexicanDB</codeph> database. The territory attribute specifies
+Spanish for the language code and Mexico for the country code. The <codeph>collation</codeph>
attribute
+specifies that the collation for the database is territory based.</p><codeblock>jdbc:derby:MexicanDB;create=true;territory=es_MX;collation=TERRITORY_BASED
</codeblock
+> </example>
+<section><title></title>For information on how <ph conref="../conrefs.dita#prod/productshortname"></ph>
handles
+collation, see "Character-based collation in <ph conref="../conrefs.dita#prod/productshortname"></ph>"
+in the <cite><ph conref="../conrefs.dita#pub/citdevelop"></ph></cite></section>
+</refbody>
+</reference>

Propchange: db/derby/docs/trunk/src/ref/rrefattribcollation.dita
------------------------------------------------------------------------------
    svn:eol-style = native



Mime
View raw message