com.mysql.cj.conf

## Class ConnectionUrlParser

- java.lang.Object
- - com.mysql.cj.conf.ConnectionUrlParser

All Implemented Interfaces:
  DatabaseUrlContainer

    public class ConnectionUrlParser
    extends Object
    implements DatabaseUrlContainer

This class parses a connection string using the general URI structure defined in RFC 3986. Instead of using a URI instance to ensure the correct syntax of the connection string, this implementation uses regular expressions which is faster but also less strict in terms of validations. This actually works better because database URLs don't exactly stick to the RFC 3986 rules.

scheme://authority/path?query#fragment

This results in splitting the connection string URL and processing its internal parts:

scheme
  The protocol and subprotocol identification. Usually "jdbc:mysql:" or "mysqlx:".
authority
  Contains information about the user credentials and/or the host and port information. Unlike its definition in the RFC 3986 specification, there can be multiple authority sections separated by a single comma (,) in a connection string. It is also possible to use an alternative syntax for the user and/or host identification, that also allows setting per host connection properties, in the form of "[user[:password]@]address=(key1=value)[(key2=value)]...[,address=(key3=value)[(key4=value)]...]...".
path
  Corresponds to the database identification.
query
  The connection properties, written as "propertyName1[=[propertyValue1]][&propertyName2[=[propertyValue2]]]..."
fragment
  The fragment section is ignored in Connector/J connection strings.

### Nested Class Summary

Nested Classes
`static class` `ConnectionUrlParser.Pair<T,U>` This class is a simple container for two elements.

### Field Summary

Fields
`private static String` `ADDRESS_EQUALS_HOST_INFO_PREFIX`
`private static Pattern` `ADDRESS_EQUALS_HOST_PTRN`
`private String` `authority`
`private String` `baseConnectionString`
`private static Pattern` `CONNECTION_STRING_PTRN`
`private static String` `DUMMY_SCHEMA`
`private static Pattern` `GENERIC_HOST_PTRN`
`private static Pattern` `HOST_LIST_PTRN`
`private static String` `HOSTS_LIST_CLOSING_MARKERS`
`private static String` `HOSTS_LIST_OPENING_MARKERS`
`private static String` `HOSTS_SEPARATOR`
`private static String` `KEY_VALUE_HOST_INFO_CLOSING_MARKER`
`private static String` `KEY_VALUE_HOST_INFO_OPENING_MARKER`
`private static Pattern` `KEY_VALUE_HOST_PTRN`
`private List<HostInfo>` `parsedHosts`
`private Map<String,String>` `parsedProperties`
`private String` `path`
`private static Pattern` `PROPERTIES_PTRN`
`private String` `query`
`private String` `scheme`
`private static Pattern` `SCHEME_PTRN`
`private static String` `USER_HOST_SEPARATOR`
`private static String` `USER_PASS_SEPARATOR`

### Constructor Summary

Constructors
`private` `ConnectionUrlParser(String connString)` Constructs a connection string parser for the given connection string.

### Method Summary

All Methods Static Methods Instance Methods Concrete Methods
`private HostInfo` `buildHostInfoForEmptyHost(String user, String password, String hostInfo)` Builds an `HostInfo` instance for empty host authority segments.
`private HostInfo` `buildHostInfoResortingToAddressEqualsSyntaxParser(String user, String password, String hostInfo)` Parses the host information using the alternate syntax "address=(key1=value1)(key2=value2)...".
`private HostInfo` `buildHostInfoResortingToGenericSyntaxParser(String user, String password, String hostInfo)` Parses the host information using the generic syntax "host:port".
`private HostInfo` `buildHostInfoResortingToKeyValueSyntaxParser(String user, String password, String hostInfo)` Parses the host information using the alternate syntax "(key1=value1, key2=value2, ...)".
`private List<HostInfo>` `buildHostInfoResortingToSubHostsListParser(String user, String password, String hostInfo)` Parses the host information using the alternate sub hosts lists syntax "[host1, host2, ...]".
`private HostInfo` `buildHostInfoResortingToUriParser(String user, String password, String hostInfo)` Parses the host information resorting to a URI object.
`private static String` `decode(String text)` URL-decode the given string.
`private static String` `decodeSkippingPlusSign(String text)` URL-decode the given string skipping all occurrences of the plus sign.
`String` `getAuthority()` Returns the authority section.
`String` `getDatabaseUrl()` Returns the original database URL that produced this connection string parser.
`List<HostInfo>` `getHosts()` Returns the hosts information.
`String` `getPath()` Returns the path section.
`Map<String,String>` `getProperties()` Returns the properties map contained in this connection string.
`String` `getQuery()` Returns the query section.
`String` `getScheme()` Returns the scheme section.
`static boolean` `isConnectionStringSupported(String connString)` Checks if the scheme part of given connection string matches one of the `ConnectionUrl.Type`s supported by Connector/J.
`private void` `parseAuthoritySection()` Parses the authority section (user and/or host identification) of the connection string URI.
`private void` `parseAuthoritySegment(String authSegment)` Parses the given sub authority segment, which can take one of the following syntaxes: _user_:_password_@_host_:_port_ _user_:_password_@(key1=value1,key2=value2,...) _user_:_password_@address=(key1=value1)(key2=value2)...
`private void` `parseConnectionString()` Splits the connection string in its main sections.
`static ConnectionUrlParser` `parseConnectionString(String connString)` Static factory method for constructing instances of this class.
`static ConnectionUrlParser.Pair<String,Integer>` `parseHostPortPair(String hostInfo)` Parses a host:port pair and returns the two elements in a `ConnectionUrlParser.Pair`
`private void` `parseQuerySection()` Parses the connection properties section and stores the extracted key/value pairs into a local map.
`static ConnectionUrlParser.Pair<String,String>` `parseUserInfo(String userInfo)` Parses the given user information which is formed by the parts [user][:password].
`private Map<String,String>` `processKeyValuePattern(Pattern pattern, String input)` Takes a two-matching-groups (respectively named "key" and "value") pattern which is successively tested against the given string and produces a key/value map with the matched values.
`private ConnectionUrlParser.Pair<String,String>` `splitByUserInfoAndHostInfo(String authSegment)` Splits the given authority segment in the user information part and the host part.
`String` `toString()` Returns a string representation of this object.

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

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

### Field Detail

#### DUMMY_SCHEMA

    private static final String DUMMY_SCHEMA

See Also:
  Constant Field Values

#### USER_PASS_SEPARATOR

    private static final String USER_PASS_SEPARATOR

See Also:
  Constant Field Values

#### USER_HOST_SEPARATOR

    private static final String USER_HOST_SEPARATOR

See Also:
  Constant Field Values

#### HOSTS_SEPARATOR

    private static final String HOSTS_SEPARATOR

See Also:
  Constant Field Values

#### KEY_VALUE_HOST_INFO_OPENING_MARKER

    private static final String KEY_VALUE_HOST_INFO_OPENING_MARKER

See Also:
  Constant Field Values

#### KEY_VALUE_HOST_INFO_CLOSING_MARKER

    private static final String KEY_VALUE_HOST_INFO_CLOSING_MARKER

See Also:
  Constant Field Values

#### HOSTS_LIST_OPENING_MARKERS

    private static final String HOSTS_LIST_OPENING_MARKERS

See Also:
  Constant Field Values

#### HOSTS_LIST_CLOSING_MARKERS

    private static final String HOSTS_LIST_CLOSING_MARKERS

See Also:
  Constant Field Values

#### ADDRESS_EQUALS_HOST_INFO_PREFIX

    private static final String ADDRESS_EQUALS_HOST_INFO_PREFIX

See Also:
  Constant Field Values

#### CONNECTION_STRING_PTRN

    private static final Pattern CONNECTION_STRING_PTRN

#### SCHEME_PTRN

    private static final Pattern SCHEME_PTRN

#### HOST_LIST_PTRN

    private static final Pattern HOST_LIST_PTRN

#### GENERIC_HOST_PTRN

    private static final Pattern GENERIC_HOST_PTRN

#### KEY_VALUE_HOST_PTRN

    private static final Pattern KEY_VALUE_HOST_PTRN

#### ADDRESS_EQUALS_HOST_PTRN

    private static final Pattern ADDRESS_EQUALS_HOST_PTRN

#### PROPERTIES_PTRN

    private static final Pattern PROPERTIES_PTRN

#### baseConnectionString

    private final String baseConnectionString

#### scheme

    private String scheme

#### authority

    private String authority

#### path

    private String path

#### query

    private String query

#### parsedHosts

    private List<HostInfo> parsedHosts

#### parsedProperties

    private Map<String,String> parsedProperties

### Constructor Detail

#### ConnectionUrlParser

    private ConnectionUrlParser(String connString)

Constructs a connection string parser for the given connection string.

Parameters:
  `connString` - the connection string to parse

### Method Detail

#### parseConnectionString

    public static ConnectionUrlParser parseConnectionString(String connString)

Static factory method for constructing instances of this class.

Parameters:
  `connString` - The connection string to parse.
Returns:
  an instance of `ConnectionUrlParser`

#### isConnectionStringSupported

    public static boolean isConnectionStringSupported(String connString)

Checks if the scheme part of given connection string matches one of the `ConnectionUrl.Type`s supported by Connector/J. Throws `WrongArgumentException` if connString is null.

Parameters:
  `connString` - connection string
Returns:
  true if supported

#### parseConnectionString

    private void parseConnectionString()

Splits the connection string in its main sections.

#### parseAuthoritySection

    private void parseAuthoritySection()

Parses the authority section (user and/or host identification) of the connection string URI.

#### parseAuthoritySegment

    private void parseAuthoritySegment(String authSegment)

Parses the given sub authority segment, which can take one of the following syntaxes:

- _user_:_password_@_host_:_port_
- _user_:_password_@(key1=value1,key2=value2,...)
- _user_:_password_@address=(key1=value1)(key2=value2)...
- _user_:_password_@[_any_of_the_above_1_,_any_of_the_above_2_,...]

Most of the above placeholders can be omitted, representing a null, empty, or default value. The placeholder _host_, can be a host name, IPv4 or IPv6. This parser doesn't check IP syntax. IPv6 addresses are enclosed by square brackets ([::1]). The placeholder _any_of_the_above_?_ can be any of the above except for the user information part (_user_:_password_@). When the symbol ":" is not used, it means an null/empty password or a default (HostInfo.NO_PORT) port, respectively. When the symbol "@" is not used, it means that the authority part doesn't contain user information (depending on the scheme type can still be provided via key=value pairs).

Parameters:
  `authSegment` - the string containing the authority segment

#### buildHostInfoForEmptyHost

    private HostInfo buildHostInfoForEmptyHost(String user,
                                               String password,
                                               String hostInfo)

Builds an `HostInfo` instance for empty host authority segments.

Parameters:
  `user` - the user to include in the final `HostInfo`
  `password` - the password to include in the final `HostInfo`
  `hostInfo` - the string containing the host information part
Returns:
  the `HostInfo` instance containing the parsed information or `null` if the host part is not empty

#### buildHostInfoResortingToUriParser

    private HostInfo buildHostInfoResortingToUriParser(String user,
                                                       String password,
                                                       String hostInfo)

Parses the host information resorting to a URI object. This process handles most single-host well formed addresses.

Parameters:
  `user` - the user to include in the final `HostInfo`
  `password` - the password to include in the final `HostInfo`
  `hostInfo` - the string containing the host information part
Returns:
  the `HostInfo` instance containing the parsed information or `null` if unable to parse the host information

#### buildHostInfoResortingToSubHostsListParser

    private List<HostInfo> buildHostInfoResortingToSubHostsListParser(String user,
                                                                      String password,
                                                                      String hostInfo)

Parses the host information using the alternate sub hosts lists syntax "[host1, host2, ...]".

Parameters:
  `user` - the user to include in all the resulting `HostInfo`
  `password` - the password to include in all the resulting `HostInfo`
  `hostInfo` - the string containing the host information part
Returns:
  a list with all `HostInfo` instances containing the parsed information or `null` if unable to parse the host information

#### buildHostInfoResortingToKeyValueSyntaxParser

    private HostInfo buildHostInfoResortingToKeyValueSyntaxParser(String user,
                                                                  String password,
                                                                  String hostInfo)

Parses the host information using the alternate syntax "(key1=value1, key2=value2, ...)".

Parameters:
  `user` - the user to include in the resulting `HostInfo`
  `password` - the password to include in the resulting `HostInfo`
  `hostInfo` - the string containing the host information part
Returns:
  the `HostInfo` instance containing the parsed information or `null` if unable to parse the host information

#### buildHostInfoResortingToAddressEqualsSyntaxParser

    private HostInfo buildHostInfoResortingToAddressEqualsSyntaxParser(String user,
                                                                       String password,
                                                                       String hostInfo)

Parses the host information using the alternate syntax "address=(key1=value1)(key2=value2)...".

Parameters:
  `user` - the user to include in the resulting `HostInfo`
  `password` - the password to include in the resulting `HostInfo`
  `hostInfo` - the string containing the host information part
Returns:
  the `HostInfo` instance containing the parsed information or `null` if unable to parse the host information

#### buildHostInfoResortingToGenericSyntaxParser

    private HostInfo buildHostInfoResortingToGenericSyntaxParser(String user,
                                                                 String password,
                                                                 String hostInfo)

Parses the host information using the generic syntax "host:port".

Parameters:
  `user` - the user to include in the resulting `HostInfo`
  `password` - the password to include in the resulting `HostInfo`
  `hostInfo` - the string containing the host information part
Returns:
  the `HostInfo` instance containing the parsed information or `null` if unable to parse the host information

#### splitByUserInfoAndHostInfo

    private ConnectionUrlParser.Pair<String,String> splitByUserInfoAndHostInfo(String authSegment)

Splits the given authority segment in the user information part and the host part.

Parameters:
  `authSegment` - the string containing the authority segment, i.e., the user and host information parts
Returns:
  a `ConnectionUrlParser.Pair` containing the user information in the left side and the host information in the right

#### parseUserInfo

    public static ConnectionUrlParser.Pair<String,String> parseUserInfo(String userInfo)

Parses the given user information which is formed by the parts [user][:password].

Parameters:
  `userInfo` - the string containing the user information
Returns:
  a `ConnectionUrlParser.Pair` containing the user and password information or null if the user information can't be parsed

#### parseHostPortPair

    public static ConnectionUrlParser.Pair<String,Integer> parseHostPortPair(String hostInfo)

Parses a host:port pair and returns the two elements in a `ConnectionUrlParser.Pair`

Parameters:
  `hostInfo` - the host:pair to parse
Returns:
  a `ConnectionUrlParser.Pair` containing the host and port information or null if the host information can't be parsed

#### parseQuerySection

    private void parseQuerySection()

Parses the connection properties section and stores the extracted key/value pairs into a local map.

#### processKeyValuePattern

    private Map<String,String> processKeyValuePattern(Pattern pattern,
                                                      String input)

Takes a two-matching-groups (respectively named "key" and "value") pattern which is successively tested against the given string and produces a key/value map with the matched values. The given pattern must ensure that there are no leftovers between successive tests, i.e., the end of the previous match must coincide with the beginning of the next.

Parameters:
  `pattern` - the regular expression pattern to match against to
  `input` - the input string
Returns:
  a key/value map containing the matched values

#### decode

    private static String decode(String text)

URL-decode the given string.

Parameters:
  `text` - the string to decode
Returns:
  the decoded string

#### decodeSkippingPlusSign

    private static String decodeSkippingPlusSign(String text)

URL-decode the given string skipping all occurrences of the plus sign.

Parameters:
  `text` - the string to decode
Returns:
  the decoded string

#### getDatabaseUrl

    public String getDatabaseUrl()

Returns the original database URL that produced this connection string parser.

Specified by:
  `getDatabaseUrl` in interface `DatabaseUrlContainer`
Returns:
  the original database URL

#### getScheme

    public String getScheme()

Returns the scheme section.

Returns:
  the scheme section

#### getAuthority

    public String getAuthority()

Returns the authority section.

Returns:
  the authority section

#### getPath

    public String getPath()

Returns the path section.

Returns:
  the path section

#### getQuery

    public String getQuery()

Returns the query section.

Returns:
  the query section

#### getHosts

    public List<HostInfo> getHosts()

Returns the hosts information.

Returns:
  the hosts information

#### getProperties

    public Map<String,String> getProperties()

Returns the properties map contained in this connection string.

Returns:
  the properties map

#### toString

    public String toString()

Returns a string representation of this object.

Overrides:
  `toString` in class `Object`
Returns:
  a string representation of this object

Copyright © 2016, 2024, Oracle and/or its affiliates.