JDBC-492 Document deprecation of translation / mapping path in Jaybir…

…d 3.1

src/documentation/release_notes.md

@@ -1170,12 +1170,33 @@ Jaybird 3.1 will very likely drop support for Java 7 (this decision is not final
 
 The following methods will be removed in Jaybird 3.1:
 
--   `CharacterTranslator.getMapping()`, use `CharacterTranslator.getMapping(char)`
-    instead.
+-   Character set mapping (translation) will be removed entirely. Connection 
+    property `useTranslation` (and it's alias `mapping_path`) will no longer be
+    available.
+
+    Similar effects can be achieved by a custom encoding implementation.
+
+    As part of this change the following parts of the implementation will be 
+    removed (note that most are internal to Jaybird):
 
-    Complete removal of the character translation support is also being
-    considered, as similar effects can be achieved by a custom encoding 
-    implementation.
+    -   `org.firebirdsql.encodings.CharacterTranslator` will be removed entirely
+    -   `DatatypeCoder#encodeString(String value, String javaEncoding, String mappingPath)`
+    -   `DatatypeCoder#encodeString(String value, Encoding encoding, String mappingPath)`
+    -   `DatatypeCoder#decodeString(byte[] value, String javaEncoding, String mappingPath)`
+    -   `DatatypeCoder#decodeString(byte[] value, Encoding encoding, String mappingPath)`
+    -   `Encoding#withTranslation(CharacterTranslator translator)`
+    -   `EncodingFactory#getEncoding(String encoding, String mappingPath)`
+    -   `EncodingFactory#getEncoding(Charset charset, String mappingPath)`
+    -   `FirebirdConnectionProperties#setUseTranslation(String translationPath)` (and on data sources)
+    -   `FirebirdConnectionProperties#getUseTranslation` (and on data sources)
+    -   `IEncodingFactory#getCharacterTranslator(String mappingPath)`
+
+-   The following connection properties will be removed:
+
+    -   `useTranslation`: See previous item
+    -   `octetsAsBytes`: Since Jaybird 3 octets is always handled as `BINARY`
+    -   `noResultSetTracking`: Option does nothing since Jaybird 3
+    -   `paranoia_mode`: Option does nothing since Jaybird 2.2 (maybe earlier)
 
 -   `GDSHelper.iscVaxInteger(byte[] buffer, int pos, int length)` use
     `VaxEncoding.iscVaxInteger(byte[] buffer, int startPosition, int length)`
@@ -1187,6 +1208,8 @@ The following methods will be removed in Jaybird 3.1:
     `MaintenanceManager.commitTransaction(long transactionId)` instead.
 -   `MaintenanceManager.rollbackTransaction(int transactionId)`, use
     `MaintenanceManager.rollbackTransaction(long transactionId)` instead.
+-   `FBBlob#copyCharacterStream(Reader reader, long length, String encoding)`
+-   `FBBlob#copyCharacterStream(Reader reader, String encoding)`  
 
 ### Removal of deprecated constants ###
 

src/main/org/firebirdsql/encodings/CharacterTranslator.java

@@ -24,7 +24,10 @@
 
 /**
  * Class responsible for character translation.
+ *
+ * @deprecated To be removed in Jaybird 3.1
  */
+@Deprecated
 public final class CharacterTranslator {
 
     /**
@@ -49,7 +52,8 @@ public final class CharacterTranslator {
     private final char[] mapping;
 
     private CharacterTranslator(char[] mapping) {
-        assert mapping.length == FULL_CHAR_RANGE : "Invalid length for mapping table"; // need to cover all possible char values
+        assert mapping.length == FULL_CHAR_RANGE
+                : "Invalid length for mapping table"; // need to cover all possible char values
         this.mapping = mapping;
     }
 

src/main/org/firebirdsql/encodings/Encoding.java

@@ -69,7 +69,9 @@ public interface Encoding {
      * @param translator
      *         The translation to apply
      * @return The derived Encoding, or this encoding if {@code translator} is {@code null}
+     * @deprecated To be removed in Jaybird 3.1
      */
+    @Deprecated
     Encoding withTranslation(CharacterTranslator translator);
 
     /**

src/main/org/firebirdsql/encodings/EncodingFactory.java

@@ -596,8 +596,7 @@ public static Encoding getEncoding(Charset charset) {
      * @param mappingPath
      *         Resource file with alternative character mapping
      * @return Instance of {@link Encoding}
-     * @deprecated Use {@link #getEncodingForCharsetAlias(String, Encoding)} and {@link
-     *             Encoding#withTranslation(CharacterTranslator)}
+     * @deprecated To be removed in Jaybird 3.1, use {@link #getEncodingForCharsetAlias(String)}
      */
     @Deprecated
     @SuppressWarnings("deprecation")
@@ -624,8 +623,7 @@ public static Encoding getEncoding(String encoding, String mappingPath) throws S
      * @param mappingPath
      *         Resource file with alternative character mapping
      * @return Instance of {@link Encoding}
-     * @deprecated Use {@link #getEncodingForCharset(java.nio.charset.Charset, Encoding)} and {@link
-     *             Encoding#withTranslation(CharacterTranslator)}
+     * @deprecated To be removed in Jaybird 3.1, use {@link #getEncodingForCharset(Charset)}
      */
     @Deprecated
     @SuppressWarnings("deprecation")

src/main/org/firebirdsql/encodings/IEncodingFactory.java

@@ -179,7 +179,9 @@ public interface IEncodingFactory {
      *         Path of the file with mapping definition
      * @return Instance of CharacterTranslator
      * @throws java.sql.SQLException
+     * @deprecated To be removed in Jaybird 3.1
      */
+    @Deprecated
     CharacterTranslator getCharacterTranslator(String mappingPath) throws SQLException;
 
     /**

src/main/org/firebirdsql/gds/ng/DatatypeCoder.java

@@ -143,9 +143,15 @@ public interface DatatypeCoder {
      * @return The value of {@code value} as a {@code byte} array
      * @throws java.sql.SQLException if the given encoding cannot be found, or an error
      *         occurs during the encoding
+     * @deprecated To be removed in Jaybird 3.1
      */
+    @Deprecated
     byte[] encodeString(String value, String javaEncoding, String mappingPath) throws SQLException;
 
+    /**
+     * @deprecated To be removed in Jaybird 3.1
+     */
+    @Deprecated
     byte[] encodeString(String value, Encoding encoding, String mappingPath) throws SQLException;
 
     /**
@@ -157,9 +163,15 @@ public interface DatatypeCoder {
      * @return The decoded {@code String}
      * @throws java.sql.SQLException if the given encoding cannot be found, or an
      *         error occurs during the decoding
+     * @deprecated To be removed in Jaybird 3.1
      */
+    @Deprecated
     String decodeString(byte[] value, String javaEncoding, String mappingPath) throws SQLException;
 
+    /**
+     * @deprecated To be removed in Jaybird 3.1
+     */
+    @Deprecated
     String decodeString(byte[] value, Encoding encoding, String mappingPath) throws SQLException;
 
     /**

src/main/org/firebirdsql/jdbc/FBBlob.java

@@ -489,7 +489,9 @@ public void copyStream(InputStream inputStream) throws SQLException {
      * @param reader the source of data to copy
      * @param length The maximum number of bytes to copy, or {@code -1} to read the whole stream
      * @param encoding The encoding used in the character stream
+     * @deprecated Method signature will change incompatibly in Jaybird 3.1
      */
+    @Deprecated
     public void copyCharacterStream(Reader reader, long length, String encoding) throws SQLException {
         if (length == -1L) {
             copyCharacterStream(reader, encoding);
@@ -523,7 +525,9 @@ public void copyCharacterStream(Reader reader, long length, String encoding) thr
      *
      * @param reader the source of data to copy
      * @param encoding The encoding used in the character stream
+     * @deprecated Method signature will change incompatibly in Jaybird 3.1
      */
+    @Deprecated
     public void copyCharacterStream(Reader reader, String encoding) throws SQLException {
         try (OutputStream os = setBinaryStream(1);
              OutputStreamWriter osw = encoding != null

src/main/org/firebirdsql/jdbc/FirebirdConnectionProperties.java

@@ -118,13 +118,17 @@ public interface FirebirdConnectionProperties {
 
     /**
      * @return path to the character translation table.
+     * @deprecated To be removed in Jaybird 3.1
      */
+    @Deprecated
     String getUseTranslation();
 
     /**
      * @param translationPath
      *         path to the character translation table.
+     * @deprecated To be removed in Jaybird 3.1
      */
+    @Deprecated
     void setUseTranslation(String translationPath);
 
     /**