Package com.apple.foundationdb.relational.jdbc

package com.apple.foundationdb.relational.jdbc
Relational JDBC Driver The Relational JDBC URL starts with jdbc:relational://. We use the same JDBC URL format as mysql/postgres JDBC drivers; i.e. jdbc:relational://HOST[:PORT] to specify the remote server and port. If no HOST+PORT specified, then the URL refers to an `inprocess` server; i.e.. a server running in the current process which is accessed directly without RPC and without serializations. The URL path can specifes the database to connect to. The query string is used for passing options. For example: 
  jdbc:relational://127.0.0.1/__SYS
  jdbc:relational://127.0.0.1
  jdbc:relational://localhost/__SYS
  jdbc:relational://relational.apple.com:1234/__SYS
  jdbc:relational://relational.apple.com:1234/__SYS?schema=TMPL&options=X
  jdbc:relational:///__SYS
  jdbc:relational:///__SYS?schema=TMPL&options=X

Exceptions

Exceptions will for the most part come up out of RPC or will originate over on the server. There are two types currently; handled SQLExceptions and unhandled grpc StatusRuntimeException; the latter will usually be opaque UNKNOWNs or INTERNALS at least until we develop better handling.

Server-Side/Client-Side SQLExceptions

SQLExceptions thrown on the server-side will manifest on the client-side as SQLExceptions populated with the originals' messages, SQLCodes, and "vendor" error code if present. The client-side type may be that of the original but it may also be just a flat SQLException if the type is not publicly accessible to the grpc module managing the transforms (fdb-relational-api is NOT a dependency of fdb-relational-grpc currently so the likes of ContextualSQLException are not available to the transform code; we could change this if wanted).

The client-side * manifestation currently has no markings to indicate it a reflection of a server-side throw; its presumed server-side is the origin. We could fix this easy enough; e.g. server-side originating exceptions show in the client as a ServerSideOriginatingSQLException (or any other such marker).

Do we want client-side SQLException to include cause if present (currently it does)? Do we want the client-side to include server-side stack trace (probably not)?

StatusRuntimeException

Server- or network-originated unhandled exceptions will bubble up on the client-side as instances of StatusRuntimeException; i.e. RuntimeExceptions (this behavior is of GRCP). We'll tamper this phenomenon as we learn of the type of exceptions we'll be seeing. We've installed an interceptor for the JDBCService to catch unhandled SQLExceptions and which we can enhance as we learn more about the types of problems we'll see.