NoSQLHandleConfig¶

class borneo.NoSQLHandleConfig(endpoint=None, provider=None)[source]¶

Bases: object

An instance of this class is required by NoSQLHandle.

NoSQLHandleConfig groups parameters used to configure a NoSQLHandle. It also provides a way to default common parameters for use by NoSQLHandle methods. When creating a NoSQLHandle, the NoSQLHandleConfig instance is copied so modification operations on the instance have no effect on existing handles which are immutable. NoSQLHandle state with default values can be overridden in individual operations.

The service endpoint is used to connect to the Oracle NoSQL Database Cloud Service or, if on-premise, the Oracle NoSQL Database proxy server. It should be a string or a Region.

If a string is provided to endpoint argument, there is flexibility in how endpoints are specified. A fully specified endpoint is of the format:

http[s]://host:port

It also accepts portions of a fully specified endpoint, including a region id (see Region) string if using the Cloud service. A valid endpoint is one of these:

region id string (cloud service only)

a string with the syntax [http[s]://]host[:port]

For example, these are valid endpoint arguments:

us-ashburn-1 (equivalent to using Region Regions.US_ASHBURN_1 as the endpoint argument)

nosql.us-ashburn-1.oci.oraclecloud.com (equivalent to using Region Regions.US_ASHBURN_1 as the endpoint argument)

https://nosql.us-ashburn-1.oci.oraclecloud.com:443

localhost:8080 - used for connecting to a Cloud Simulator instance running locally on port 8080

https://machine-hosting-proxy:443

When using the endpoint (vs region id) syntax, if the port is omitted, the endpoint uses 8080 if protocol is http, and 443 in all other cases. If the protocol is omitted, the endpoint uses https if the port is 443, and http in all other cases.

When using the Oracle NoSQL Database Cloud Service, it is recommended that a Region object is provided rather than a Region’s id string.

If a Region object is provided to endpoint argument, See Regions for information on available regions. For example:

Regions.US_ASHBURN_1

For cloud service, one or both of endpoint and provider must be set. For other scenarios, endpoint is required while provider is optional.

Parameters:	endpoint (str or Region) – identifies a server, region id or `Region` for use by the NoSQLHandle. provider (AuthorizationProvider) – `AuthorizationProvider` to use for the handle.
Raises:	IllegalArgumentException – raises the exception if the endpoint is None or malformed.

Methods Summary

`clone`()	All the configurations will be copied.
`configure_default_retry_handler`(num_retries, …)	Sets the `RetryHandler` using a default retry handler configured with the specified number of retries and a static delay.
`get_authorization_provider`()	Returns the `AuthorizationProvider` configured for the handle, or None.
`get_consistency`()	Returns the configured default `Consistency`, None if it has not been configured.
`get_default_compartment`()	Cloud service only.
`get_default_consistency`()	Returns the default consistency value that will be used by the system.
`get_default_table_request_timeout`()	Returns the default value for a table request timeout.
`get_default_timeout`()	Returns the default value for request timeout in milliseconds.
`get_logger`()	Returns the logger, or None if not configured by user.
`get_max_content_length`()	Returns the maximum size, in bytes, of a request operation payload.
`get_pool_connections`()	Returns the number of connection pools to cache.
`get_pool_maxsize`()	Returns the maximum number of individual connections to use to connect to the service.
`get_region`()	Cloud service only.
`get_retry_handler`()	Returns the `RetryHandler` configured for the handle, or None if None is set.
`get_service_url`()	Returns the url to use for the `NoSQLHandle` connection.
`get_ssl_ca_certs`()	Returns the SSL CA certificates.
`get_ssl_cipher_suites`()	Returns the SSL cipher suites to enable.
`get_ssl_protocol`()	Returns the SSL protocols to enable.
`get_table_request_timeout`()	Returns the configured table request timeout value, in milliseconds.
`get_timeout`()	Returns the configured request timeout value, in milliseconds, 0 if it has not been set.
`set_authorization_provider`(provider)	Sets the `AuthorizationProvider` to use for the handle.
`set_consistency`(consistency)	Sets the default request `Consistency`.
`set_default_compartment`(compartment)	Cloud service only.
`set_default_rate_limiting_percentage`(percent)	Cloud service only.
`set_logger`(logger)	Sets the logger used for the driver.
`set_max_content_length`(max_content_length)	Sets the maximum size in bytes of request payloads.
`set_pool_connections`(pool_connections)	Sets the number of connection pools to cache.
`set_pool_maxsize`(pool_maxsize)	Sets the maximum number of individual connections to use to connect to to the service.
`set_rate_limiting_enabled`(enable)	Cloud service only.
`set_retry_handler`(retry_handler)	Sets the `RetryHandler` to use for the handle.
`set_ssl_ca_certs`(ssl_ca_certs)	On-premise only.
`set_ssl_cipher_suites`(ssl_ciphers)	Set SSL cipher suites to enable.
`set_ssl_protocol`(ssl_protocol)	Set SSL protocol to enable.
`set_table_request_timeout`(table_request_timeout)	Sets the default table request timeout.
`set_timeout`(timeout)	Sets the default request timeout in milliseconds, the default timeout is 5 seconds.

Methods Documentation

clone()[source]¶

All the configurations will be copied.

Returns:	the copy of the instance.
Return type:	NoSQLHandleConfig

configure_default_retry_handler(num_retries, delay_s)[source]¶

Sets the RetryHandler using a default retry handler configured with the specified number of retries and a static delay. A delay of 0 means “use the default delay algorithm” which is an incremental backoff algorithm. A non-zero delay will work but is not recommended for production systems as it is not flexible.

The default retry handler will not retry exceptions of type OperationThrottlingException. The reason is that these operations are long-running, and while technically they can be retried, an immediate retry is unlikely to succeed because of the low rates allowed for these operations.

Parameters:	num_retries (int) – the number of retries to perform automatically. This parameter may be 0 for no retries. delay_s (int) – the delay, in seconds. Pass 0 to use the default delay algorithm.
Returns:	self.
Raises:	IllegalArgumentException – raises the exception if num_retries or delay_s is a negative number.

get_authorization_provider()[source]¶

Returns the AuthorizationProvider configured for the handle, or None.

Returns:	the AuthorizationProvider.
Return type:	AuthorizationProvider

get_consistency()[source]¶

Returns the configured default Consistency, None if it has not been configured.

Returns:	the consistency, or None if it has not been configured.
Return type:	Consistency

get_default_compartment()[source]¶

Cloud service only.

Returns the default compartment to use for requests or None if not set. The value may be a compartment name or id, as set by set_default_compartment().

Returns:	the compartment, or None.
Return type:	str or None

get_default_consistency()[source]¶

Returns the default consistency value that will be used by the system. If consistency has been set using set_consistency(), that will be returned. If not a default value of Consistency.EVENTUAL is returned.

Returns:	the default consistency.
Return type:	Consistency

get_default_table_request_timeout()[source]¶

Returns the default value for a table request timeout. If there is no configured timeout or it is configured as 0, a “default” default value of 10000 milliseconds is used.

Returns:	the default timeout, in milliseconds.
Return type:	int

get_default_timeout()[source]¶

Returns the default value for request timeout in milliseconds. If there is no configured timeout or it is configured as 0, a “default” value of 5000 milliseconds is used.

Returns:	the default timeout, in milliseconds.
Return type:	int

get_logger()[source]¶

Returns the logger, or None if not configured by user.

Returns:	the logger.
Return type:	Logger

get_max_content_length()[source]¶

Returns the maximum size, in bytes, of a request operation payload. On-premise only. This value is ignored for cloud operations.

Returns:	the size.
Return type:	int

get_pool_connections()[source]¶

Returns the number of connection pools to cache.

Returns:	the number of connection pools.
Return type:	int

get_pool_maxsize()[source]¶

Returns the maximum number of individual connections to use to connect to the service. Each request/response pair uses a connection. The pool exists to allow concurrent requests and will bound the number of concurrent requests. Additional requests will wait for a connection to become available.

Returns:	the pool size.
Return type:	int

get_region()[source]¶

Cloud service only.

Returns the region will be accessed by the NoSQLHandle.

Returns:	the region.
Return type:	Region

get_retry_handler()[source]¶

Returns the RetryHandler configured for the handle, or None if None is set.

Returns:	the handler.
Return type:	RetryHandler

get_service_url()[source]¶

Returns the url to use for the NoSQLHandle connection.

Returns:	the url.
Return type:	ParseResult

get_ssl_ca_certs()[source]¶

Returns the SSL CA certificates.

Returns:	ssl ca certificates.
Return type:	str

get_ssl_cipher_suites()[source]¶

Returns the SSL cipher suites to enable.

Returns:	ssl ciphers in a string in the OpenSSL cipher list format.
Return type:	str

get_ssl_protocol()[source]¶

Returns the SSL protocols to enable.

Returns:	ssl protocols.
Return type:	int

get_table_request_timeout()[source]¶

Returns the configured table request timeout value, in milliseconds. The table request timeout default can be specified independently to allow it to be larger than a typical data request. If it is not specified the default table request timeout of 10000 is used.

Returns:	the timeout, in milliseconds, or 0 if it has not been set.
Return type:	int

get_timeout()[source]¶

Returns the configured request timeout value, in milliseconds, 0 if it has not been set.

Returns:	the timeout, in milliseconds, or 0 if it has not been set.
Return type:	int

set_authorization_provider(provider)[source]¶

Sets the AuthorizationProvider to use for the handle. The provider must be safely usable by multiple threads.

Parameters:	provider (AuthorizationProvider) – the AuthorizationProvider.
Returns:	self.
Raises:	IllegalArgumentException – raises the exception if provider is not an instance of `AuthorizationProvider`.

set_consistency(consistency)[source]¶

Sets the default request Consistency. If not set in this object or by a specific request, the default consistency used is Consistency.EVENTUAL.

Parameters:	consistency (Consistency) – the consistency.
Returns:	self.
Raises:	IllegalArgumentException – raises the exception if consistency is not Consistency.ABSOLUTE or Consistency.EVENTUAL.

set_default_compartment(compartment)[source]¶

Cloud service only.

Sets the default compartment to use for requests sent using the handle. Setting the default is optional and if set it is overridden by any compartment specified in a request or table name. If no compartment is set for a request, either using this default or by specification in a request, the behavior varies with how the application is authenticated:

If authenticated with a user identity the default is the root compartment of the tenancy
If authenticated as an instance principal (see borneo.iam.SignatureProvider.create_with_instance_principal() ) the compartment id (OCID) must be specified by either using this method or in each Request object. If not an exception is thrown.

Parameters:	compartment (str) – may be either the name of a compartment or the id (OCID) of a compartment.
Returns:	self.
Raises:	IllegalArgumentException – raises the exception if compartment is not a string.

set_default_rate_limiting_percentage(percent)[source]¶

Cloud service only.

Sets a default percentage of table limits to use. This may be useful for cases where a client should only use a portion of full table limits. This only applies if rate limiting is enabled using set_rate_limiting_enabled().

The default for this value is 100.0 (full table limits).

Parameters:	percent (int or float or Decimal) – the percentage of table limits to use. This value must be positive.
Returns:	self.
Raises:	IllegalArgumentException – raises the exception if percent is not a positive digital number.

set_logger(logger)[source]¶

Sets the logger used for the driver.

Parameters:	logger (Logger) – the logger or None, None means disable logging.
Returns:	self.
Raises:	IllegalArgumentException – raises the exception if logger is not an instance of Logger.

set_max_content_length(max_content_length)[source]¶

Sets the maximum size in bytes of request payloads. On-premise only. This setting is ignored for cloud operations. If not set, or set to zero, the default value of 32MB is used.

Parameters:	max_content_length (int) – the maximum bytes allowed in requests. Pass zero to use the default.
Returns:	self.
Raises:	IllegalArgumentException – raises the exception if max_content_length is a negative number.

set_pool_connections(pool_connections)[source]¶

Sets the number of connection pools to cache.

Parameters:	pool_connections (int) – the number of connection pools.
Returns:	self.
Raises:	IllegalArgumentException – raises the exception if pool_connections is not a positive number.

set_pool_maxsize(pool_maxsize)[source]¶

Sets the maximum number of individual connections to use to connect to to the service. Each request/response pair uses a connection. The pool exists to allow concurrent requests and will bound the number of concurrent requests. Additional requests will wait for a connection to become available.

Parameters:	pool_maxsize (int) – the pool size.
Returns:	self.
Raises:	IllegalArgumentException – raises the exception if pool_maxsize is not a positive number.

set_rate_limiting_enabled(enable)[source]¶

Cloud service only.

Enables internal rate limiting.

Parameters:	enable (bool) – If True, enable internal rate limiting, otherwise disable internal rate limiting.
Returns:	self.
Raises:	IllegalArgumentException – raises the exception if enable is not a boolean.

set_retry_handler(retry_handler)[source]¶

Sets the RetryHandler to use for the handle. If no handler is configured a default is used. The handler must be safely usable by multiple threads.

Parameters:	retry_handler (RetryHandler) – the handler.
Returns:	self.
Raises:	IllegalArgumentException – raises the exception if retry_handler is not an instance of `RetryHandler`.

set_ssl_ca_certs(ssl_ca_certs)[source]¶

On-premise only.

When running against on-premise Oracle NoSQL Database with security enabled, certificates should be specified using this method. Otherwise environment variable REQUESTS_CA_BUNDLE should be configured. See the installation guide for the configuration of REQUESTS_CA_BUNDLE.

Parameters:	ssl_ca_certs (str) – ssl ca certificates.
Returns:	self.
Raises:	IllegalArgumentException – raises the exception if ssl_ca_certs is not a string.

set_ssl_cipher_suites(ssl_ciphers)[source]¶

Set SSL cipher suites to enable.

Parameters:	ssl_ciphers (str) – ssl ciphers in a string in the OpenSSL cipher list format.
Returns:	self.
Raises:	IllegalArgumentException – raises the exception if ssl_ciphers is not a string.

set_ssl_protocol(ssl_protocol)[source]¶

Set SSL protocol to enable.

Parameters:	ssl_protocol (int) – ssl protocol version.
Returns:	self.
Raises:	IllegalArgumentException – raises the exception if ssl_protocol is a negative integer.

set_table_request_timeout(table_request_timeout)[source]¶

Sets the default table request timeout. The default timeout is 5 seconds. The table request timeout can be specified independently of that specified by set_request_timeout() because table requests can take longer and justify longer timeouts. The default timeout is 10 seconds (10000 milliseconds).

Parameters:	table_request_timeout (int) – the timeout value, in milliseconds.
Returns:	self.
Raises:	IllegalArgumentException – raises the exception if table_request_timeout is a negative number.

set_timeout(timeout)[source]¶

Sets the default request timeout in milliseconds, the default timeout is 5 seconds.

Parameters:	timeout (int) – the timeout value, in milliseconds.
Returns:	self.
Raises:	IllegalArgumentException – raises the exception if timeout is a negative number.