Proactive insights, news and tips from Oracle WebLogic Server Support. Learn Oracle from Oracle.

  • December 10, 2020

Active GridLink URLs

Stephen Felts

Active GridLink (AGL) is the data source type that provides connectivity between WebLogic Server and an Oracle Database service, which may include one or more Oracle RAC clusters or Active Data Guard sites.  As the supported topologies grow to include additional features like Global Database Services (GDS) and new features are added to the Oracle networking and database support, the complexity of the URL to access this has also gotten more complex. There are lots of examples in the documentation.  This is a short article that summarizes patterns for defining the URL string for use with AGL.

It should be obvious but let me start by saying AGL only works with the Oracle Thin Driver.

AGL data sources only support long format JDBC URLs. The supported long format pattern is basically the following (there are lots of additional properties, some of which are described below).

jdbc:oracle:thin:@(DESCRIPTION =
         ( ADDRESS = (PROTOCOL = TCP)(HOST=primary-scan)(PORT=primary-scan-port)))
         ( ADDRESS = (PROTOCOL = TCP)(HOST=secondary-scan)(PORT=secondary-scan-port)))       
    (CONNECT_DATA=(SERVICE_NAME = myservice)))

If not using SCAN, then the ADDRESS_LIST would have one or more ADDRESS attributes with HOST/PORT pairs. It's recommended to use SCAN if possible and it's recommended to use VIP addresses to avoid TCP/IP hangs.

Easy Connect (short) format URLs are not supported for AGL data sources. The following is an example of a Easy Connect URL pattern that is not supported for use with AGL data sources:


General recommendations for the URL are as follows.

- Use a single DESCRIPTION.  Avoid a DESCRIPTION_LIST to avoid connection delays.

- Use one ADDRESS_LIST per RAC cluster or Active Data Guard database.  In the example above, it assumes there are two RAC clusters.  If you have one RAC cluster, then you would have one address list.

- Put RETRY_COUNT, RETRY_DELAY, CONNECT_TIMEOUT, and TRANSPORT_CONNECT_TIMEOUT at the DESCRIPTION level so that all ADDRESS_LIST entries use the same value.  Note that these parameters are optional.  URL's that were generated with earlier releases won't have them.

- RETRY_DELAY specifies the delay, in seconds, between the connection retries.  It is new in the release.

- RETRY_COUNT is used to specify the number of times an ADDRESS list is traversed before the connection attempt is terminated. The default value is 0.  When using SCAN listeners with FAILOVER = on, setting the RETRY_COUNT parameter to 2 means the three SCAN IP addresses are traversed three times each, such that there are nine connect attempts (3 * 3).

- CONNECT_TIMEOUT is used to specify the overall time used to complete the Oracle Net connect.  Set CONNECT_TIMEOUT=90 or higher to prevent logon storms.    Do not set the oracle.net.CONNECT_TIMEOUT driver property on the datasource because it is overridden by the URL property.

- For JDBC drivers up through 12c, CONNECT_TIMEOUT is also used for the TCP/IP connection timeout for each address in the URL.  This second usage is preferred to be shorter.  In 18c and later, TRANSPORT_CONNECT_TIMEOUT was introduced. 

- The service name should be a configured application service, not a PDB or administration service.

- Specify LOAD_BALANCE=on per address list to balance the SCAN addresses.


Join the discussion

Comments ( 3 )
  • guest Tuesday, November 24, 2015

    Thanks Steve for this info - very informative

    I'd love to know the actual differences between using AGL and Generic WebLogic connection pools. I'd imagine the Connection Strings are EXACTLY the same and the only difference is AGL has the ONS infrastructure in place. Generic would rely on timeouts to failover while AGL could/would use ONS info and would never have to timeout??

  • Steve Felts Tuesday, November 24, 2015

    From a descriptor point of view, we are trying minimize the difference but we do need something to tell us that you want AGL instead of Generic. Here are the descriptor differences.

    1. URL - For AGL, it should be one or more RAC instances. For Generic, it should point to a single instance, RAC or not (but some customers point to multiple instances - we document the limitations of this approach). The URL isn't enough for the software to figure out which type is needed.

    2. FAN should be enabled for AGL but is not required. Currently, setting FAN enabled automatically makes it AGL (even if you set the type to Generic). That seems wrong so we will be changing that so that if the type is explicitly set to something other than AGL, FAN enabled will be ignored. That will allow for someone to set FAN enabled for all descriptors but it will be turned on only for AGL. It would be better if we could just default FAN enabled to true for AGL (hindsight 5 years later) but that would break existing customers that want FAN disabled (which is not recommended).

    3. Type - once #2 is in place, the only thing that distinguishes AGL vs. Generic in the descriptor will be the datasource type (new in 12.2.1).

    Setting the ONS node list is no longer necessary or recommended because of auto-ONS, which gets the information from the database server, so that's no longer a required difference.

    You might think that Generic is the degenerate case of AGL with one instance. Under the covers, there's a big difference. That's why it's important for the descriptor to tell us explicitly whether it's Generic or AGL.

    AGL needs to manage multiple instances - connections associated with each instance, an MBean per instance, etc. It uses UCP to manage ONS events, dynamically adding and removing instances, load-balancing, and affinity (but not connection pooling).

    Generic manages just a single instance and datasource MBean. It depends on connection failures (polling) to suspend the pool (flush and disable are now configurable).

  • Stephen Felts Friday, December 11, 2020
    In WLS 14.1.1 and later, fanEnabled is ignored for all explicitly defined datasource types except for AGL. That is, if a description has the type set to "GENERIC", fanEnabled is ignored. If the datasource type is not set in the descriptor, than fanEnabled indicates that it is an AGL datasource.
Please enter your name.Please provide a valid email address.Please enter a comment.CAPTCHA challenge response provided was incorrect. Please try again.