Skip to content

Commit 908b752

Browse files
Some edits for the README
1 parent 0788f5a commit 908b752

File tree

1 file changed

+47
-49
lines changed

1 file changed

+47
-49
lines changed

README.md

Lines changed: 47 additions & 49 deletions
Original file line numberDiff line numberDiff line change
@@ -103,9 +103,9 @@ Flux.usingWhen(
103103
connection ->
104104
Flux.from(connection.createStatement(
105105
"SELECT 'Hello, Oracle' FROM sys.dual")
106-
.execute())
107-
.flatMap(result ->
108-
result.map(row -> row.get(0, String.class))),
106+
.execute())
107+
.flatMap(result ->
108+
result.map(row -> row.get(0, String.class))),
109109
Connection::close)
110110
.doOnNext(System.out::println)
111111
.doOnError(Throwable::printStackTrace)
@@ -341,8 +341,8 @@ typically defer execution until a Subscriber signals demand, and not support
341341
multiple subscribers.
342342

343343
### Errors
344-
Oracle R2DBC creates R2dbcExceptions having ORA-XXXXX error codes that ared used
345-
by Oracle Database and Oracle JDBC.
344+
Oracle R2DBC creates R2dbcExceptions having the same ORA-XXXXX error codes
345+
used by Oracle Database and Oracle JDBC.
346346

347347
A reference for the ORA-XXXXX error codes can be found
348348
[here](https://docs.oracle.com/en/database/oracle/oracle-database/21/errmg/ORA-00000.html#GUID-27437B7F-F0C3-4F1F-9C6E-6780706FB0F6)
@@ -355,7 +355,8 @@ isolation is configured, then the
355355
`oracle.r2dbc.OracleR2dbcOptions.ENABLE_QUERY_RESULT_CACHE` option must also be
356356
configured as `false` to avoid phantom reads.
357357

358-
> READ COMMITTED and SERIALIZABLE are the isolation levels supported by Oracle Database
358+
> READ COMMITTED and SERIALIZABLE are the only isolation levels supported by
359+
> Oracle Database
359360
360361
Oracle Database does not support a lock wait timeout that is configurable within
361362
the scope of a transaction or session. Oracle R2DBC implements SPI methods that
@@ -385,9 +386,9 @@ connection.createStatement(
385386
"SELECT value FROM example WHERE id=:id")
386387
.bind("id", 99)
387388
```
388-
The `bind` method may either be called with a `String` valued name (or with
389-
zero-based index) to set the value of a named parameter. Parameter names
390-
are case-sensitive.
389+
The `bind` method may be called with a `String` valued name, or with zero-based
390+
index, to set the value of a named parameter. Parameter names are
391+
case-sensitive.
391392

392393
#### Batch Execution
393394
The `Statement.add()` method may be used execute a DML command multiple times
@@ -397,7 +398,7 @@ execute a SELECT query with a batch of bind values will result in an error.
397398

398399
#### Returning Generated Values
399400
The `Statement.returnGeneratedValues(String...)` method may be called to return
400-
generated values for the basic forms of `INSERT` and `UPDATE` statements.
401+
generated values from basic forms of `INSERT` and `UPDATE` statements.
401402

402403
If an empty set of column names is passed to `returnGeneratedValues`, the
403404
`Statement` will return the
@@ -410,7 +411,7 @@ of each row affected by an INSERT or UPDATE.
410411
> for more information.
411412
412413
Returning generated values is only supported for `INSERT` and `UPDATE` commands
413-
where a `RETURNING INTO` clause would be valid. For example, if a table is
414+
in which a `RETURNING INTO` clause would be valid. For example, if a table is
414415
declared as:
415416
```sql
416417
CREATE TABLE example (
@@ -470,9 +471,9 @@ OUT parameters are consumed by invoking `Result.map(Function)`:
470471
```java
471472
result.map(outParameters -> outParameters.get("greeting_out", String.class))
472473
```
473-
For a procedural call that returns multiple results, the publisher returned by
474+
If a procedural call returns multiple results, the publisher returned by
474475
`Statement.execute()` emits one `Result` for each cursor returned by
475-
`DBMS_SQL.RETURN_RESULT` in the called procedure. The order in which each
476+
`DBMS_SQL.RETURN_RESULT` in the procedure. The order in which each
476477
`Result` is emitted corresponds to the order in which the procedure returns each
477478
cursor.
478479

@@ -483,53 +484,50 @@ for the out parameters is emitted last, after the `Result` for each cursor.
483484
Oracle R2DBC supports type mappings between Java and SQL for non-standard data
484485
types of Oracle Database.
485486

486-
`javax.json.JsonObject` and `oracle.sql.json.OracleJsonObject` are supported as
487-
the Java type mappings for the `JSON` data type.
488-
489-
`java.time.Duration` is supported as the Java type mapping for the
490-
`INTERVAL DAY TO SECOND` data type.
491-
492-
`java.time.Period` is supported as the Java type mapping for the
493-
`INTERVAL YEAR TO MONTH` data type.
494-
495-
`java.time.LocalDateTime` is supported as the Java type mapping for the `DATE`
496-
data type.
487+
| Oracle SQL Type | Java Type |
488+
|---------------------------------------------------------------------------------------------------------------------------------------------------------|-----------|
489+
| [JSON](https://docs.oracle.com/en/database/oracle/oracle-database/21/sqlrf/Data-Types.html#GUID-E441F541-BA31-4E8C-B7B4-D2FB8C42D0DF) | `javax.json.JsonObject` or `oracle.sql.json.OracleJsonObject` |
490+
| [DATE](https://docs.oracle.com/en/database/oracle/oracle-database/21/sqlrf/Data-Types.html#GUID-5405B652-C30E-4F4F-9D33-9A4CB2110F1B) | `java.time.LocalDateTime` |
491+
| [INTERVAL DAY TO SECOND](https://docs.oracle.com/en/database/oracle/oracle-database/21/sqlrf/Data-Types.html#GUID-B03DD036-66F8-4BD3-AF26-6D4433EBEC1C) | `java.time.Duration` |
492+
| [INTERVAL YEAR TO MONTH](https://docs.oracle.com/en/database/oracle/oracle-database/21/sqlrf/Data-Types.html#GUID-ED59E1B3-BA8D-4711-B5C8-B0199C676A95) | `java.time.Period` |
497493
> Unlike the standard SQL type named "DATE", the Oracle Database type named
498494
> "DATE" stores values for year, month, day, hour, minute, and second. The
499495
> standard SQL type only stores year, month, and day. LocalDateTime objects are able
500496
> to store the same values as a DATE in Oracle Database.
501497
502498
### BLOB, CLOB, and NCLOB
503-
Oracle R2DBC supports reading and writing the content of large object (LOB)
504-
types.
505-
506-
#### Configuring the Prefetched Data Size
507-
When a SQL query returns the content of a LOB column, only a portion of the
508-
entire content is received in the response from Oracle Database. The portion
509-
which is received in the SQL query response is referred to as "prefetched data".
510-
Any content remaining after the prefetched data must be fetched by additional
511-
database calls.
512-
513-
For example, if a SQL query returns a LOB which is 100MB in size, then the
514-
response might include only the first 1MB of the LOB's content. Additional
499+
Oracle R2DBC allows large objects (LOBs) to be read and written as a reactive
500+
stream, or as a
501+
fully materialized value.
502+
503+
#### Prefetched LOB Data
504+
When a SQL query returns a LOB column, only a portion of the LOB's content
505+
is received in the response from Oracle Database. The portion received in the
506+
SQL query response is referred to as "prefetched data". Any content remaining
507+
after the prefetched portion must be fetched with additional database calls.
508+
509+
For example, if a SQL query returns a LOB that is 100MB in size, then the
510+
response might prefetch only the first 1MB of the LOB's content. Additional
515511
database calls would be required to fetch the remaining 99MB of content.
516512

517-
The number of prefetched bytes is configured by an `Option` named [oracle.jdbc.defaultLobPrefetchSize](https://docs.oracle.com/en/database/oracle/oracle-database/21/jajdb/oracle/jdbc/OracleConnection.html?is-external=true#CONNECTION_PROPERTY_DEFAULT_LOB_PREFETCH_SIZE)
518-
. The default value of this `Option` is 1 GB.
519-
520-
#### Streamed Type Mapping
521-
For systems in which LOB values are too large for prefetching, a smaller
522-
prefetch size may be configured. By mapping LOB columns to `Blob` or `Clob`
523-
objects, the content may be streamed over a series of non-blocking database
524-
calls.
513+
By default, Oracle R2DBC attempts to prefetch the entire content of a LOB. Oracle R2DBC will
514+
request up to 1GB of prefetched data from Oracle Database when executing a SQL
515+
query.
525516

526517
#### Materialzed Type Mapping
527518
The `Row.get(...)` method allows LOB values to be mapped into materialized
528-
types like `ByteBuffer` and `String`. If the prefetch size is large
529-
enough to have fetched the entire LOB value, then `Row.get(...)` can
530-
return a `ByteBuffer/String` without any additional database calls. However, if
531-
the LOB value is larger than the prefetch size, then `Row.get(...)` must execute
532-
a **blocking database call** to fetch the remainder of that value.
519+
types like `ByteBuffer` and `String`. If the entire LOB has been prefetched,
520+
then `Row.get(...)` can return a `ByteBuffer/String` without any additional
521+
database calls. However, if the LOB value is larger than the prefetch size, then
522+
`Row.get(...)` must execute a **blocking database call** to fetch the remainder of that value.
523+
524+
#### Streamed Type Mapping
525+
In a system that consumes very large LOBs, a very large amount of memory will be
526+
consumed if the entire LOB is prefetched. When a LOB is too large to be
527+
prefetched entirely, a smaller prefetch size can be configured using the
528+
[oracle.jdbc.defaultLobPrefetchSize](https://docs.oracle.com/en/database/oracle/oracle-database/21/jajdb/oracle/jdbc/OracleConnection.html?is-external=true#CONNECTION_PROPERTY_DEFAULT_LOB_PREFETCH_SIZE)
529+
option, and the LOB can be consumed as a stream. By mapping LOB columns to
530+
`Blob` or `Clob` objects, the content can be consumed as a reactive stream.
533531

534532
## Secure Programming Guidelines
535533
The following security related guidelines should be adhered to when programming

0 commit comments

Comments
 (0)