org.apache.calcite.avatica

## Class ConnectStringParser

- java.lang.Object
- - org.apache.calcite.avatica.ConnectStringParser

    public class ConnectStringParser
    extends Object

ConnectStringParser is a utility class that parses or creates a JDBC connect string according to the OLE DB Connection String Syntax.

This code was adapted from Mondrian's mondrian.olap.Util class. The primary differences between this and its Mondrian progenitor are:

- use of regular `Properties` for compatibility with the JDBC API (replaces Mondrian's use of its own order-preserving and case-insensitive PropertyList)
- ability to pass to `parse(java.lang.String)` a pre-existing Properties object into which properties are to be parsed, possibly overriding prior values
- use of `SQLException`s rather than unchecked `RuntimeException`s
- static members for parsing and creating connect strings

ConnectStringParser has a private constructor. Callers use the static members:

`parse(String)`
  Parses the connect string into a new Properties object.
`parse(String, Properties)`
  Parses the connect string into an existing Properties object.
`getParamString(Properties)`
  Returns a param string, quoted and escaped as needed, to represent the supplied name-value pairs.

### Field Summary

Fields
`private int` `i`
`private int` `n`
`private StringBuilder` `nameBuf`
`private String` `s`
`private StringBuilder` `valueBuf`

### Constructor Summary

Constructors
`private` `ConnectStringParser(String s)` Creates a new connect string parser.

### Method Summary

Methods
`static String` `getParamString(Properties props)` Returns a param string, quoted and escaped as needed, to represent the supplied name-value pairs.
`static Properties` `parse(String s)` Parses the connect string into a new Properties object.
`static Properties` `parse(String s, Properties props)` Parses the connect string into an existing Properties object.
`(package private) Properties` `parseInternal(Properties props)` Parses the connect string into a Properties object.
`(package private) String` `parseName()` Reads "name=".
`(package private) void` `parsePair(Properties props)` Reads "name=value;" or "name=value<EOF>".
`(package private) String` `parseQuoted(char q)` Reads a string quoted by a given character.
`(package private) String` `parseValue()` Reads "value;" or "value<EOF>"
`static Map<String,String>` `toMap(Properties properties)` Converts a `Properties` object to a ``Map`<String, String>`.

### Methods inherited from class java.lang.Object

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

### Field Detail

#### s

    private final String s

#### n

    private final int n

#### i

    private int i

#### nameBuf

    private final StringBuilder nameBuf

#### valueBuf

    private final StringBuilder valueBuf

### Constructor Detail

#### ConnectStringParser

    private ConnectStringParser(String s)

Creates a new connect string parser.

Parameters:
  `s` - connect string to parse
See Also:
  `parse(String)`, `parse(String, Properties)`

### Method Detail

#### parse

    public static Properties parse(String s)
                            throws SQLException

Parses the connect string into a new Properties object.

Parameters:
  `s` - connect string to parse
Returns:
  properties object with parsed params
Throws:
  `SQLException` - error parsing name-value pairs

#### parse

    public static Properties parse(String s,
                   Properties props)
                            throws SQLException

Parses the connect string into an existing Properties object.

Parameters:
  `s` - connect string to parse
  `props` - optional properties object, may be `null`
Returns:
  properties object with parsed params; if an input `props` was supplied, any duplicate properties will have been replaced by those from the connect string.
Throws:
  `SQLException` - error parsing name-value pairs

#### parseInternal

    Properties parseInternal(Properties props)
                       throws SQLException

Parses the connect string into a Properties object. Note that the string can only be parsed once. Subsequent calls return empty/unchanged Properties. The original `props` argument is not altered.

Parameters:
  `props` - optional properties object, may be `null`
Returns:
  properties object with parsed params; if an input `props` was supplied, any duplicate properties will have been replaced by those from the connect string.
Throws:
  `SQLException` - error parsing name-value pairs

#### parsePair

    void parsePair(Properties props)
             throws SQLException

Reads "name=value;" or "name=value<EOF>".

Throws:
  `SQLException` - error parsing value

#### parseName

    String parseName()

Reads "name=". Name can contain equals sign if equals sign is doubled.

#### parseValue

    String parseValue()
                throws SQLException

Reads "value;" or "value<EOF>"

Throws:
  `SQLException` - if find an unterminated quoted value

#### parseQuoted

    String parseQuoted(char q)
                 throws SQLException

Reads a string quoted by a given character. Occurrences of the quoting character must be doubled. For example, `parseQuoted('"')` reads `"a ""new"" string"` and returns `a "new" string`.

Throws:
  `SQLException` - if find an unterminated quoted value

#### getParamString

    public static String getParamString(Properties props)

Returns a param string, quoted and escaped as needed, to represent the supplied name-value pairs.

Parameters:
  `props` - name-value pairs
Returns:
  param string, never `null`

#### toMap

    public static Map<String,String> toMap(Properties properties)

Converts a `Properties` object to a ``Map`<String, String>`.

This is necessary because `Properties` is a dinosaur class. It ought to extend `Map<String,String>`, but instead extends ``Hashtable`<Object,Object>`.

Typical usage, to iterate over a `Properties`:

> `Properties properties;
> for (Map.Entry<String, String> entry = Util.toMap(properties).entrySet()) {
> println("key=" + entry.getKey() + ", value=" + entry.getValue());
> }`