Incorrect documentation (JavaDoc) on PoolOptions.setName()

[Brada-Groep]

The documentation (JavaDoc) on public PoolOptions setName(String) in PoolOptions.java is as follows:

Set the pool name, used when the pool shared, otherwise ignored. @param name the new name @return a reference to this, so the API can be used fluently

However, it is not ignored. When you give the PoolOptions the same name as another PoolOptions, they become one (or at least something like that).

Why is this is a problem

Because it said that it was ignored when not shared, I put a generic name on my instances. However, after one Verticle saturated all the connections inside the pool, my entire API froze. And it took me more than a full day to discover what the problem was.

Proposal

What I think the documentation should look like:

Set the pool name, used when the pool is shared. When multiple PoolOptions instances have the same name, they are merged. @param name the new name @return a reference to this, so the API can be used fluently

If the documentation was like this from the beginning, it would've saved me a lot of time. I hope this can be picked up!

My setup and how I encounterd this problem

I'd made my own custom function to create a Pool instance that was called in every worker verticle:

fun Vertx.getConnection(): Pool {
  val connection: Pool

  lateinit var props: Properties

  // [initialise props]

  val connectOptions = JDBCConnectOptions()
    .setJdbcUrl("jdbc:mysql://${props.getProperty("DATABASE_URL") ?: IllegalStateException("DATABASE_URL not found in the loaded properties file.")}")
    .setUser(GlobalData.databaseUser)
    .setPassword(GlobalData.databasePassword)

  val poolOptions = PoolOptions()
    .setMaxSize(16)
    .setIdleTimeout(15000)  // 15 second timeout
    .setConnectionTimeout(15000)  // 15 second timeout

  connection = JDBCPool.pool(this, connectOptions, poolOptions)

  println("getConnection() | Connection pool has been created successfully")
  return connection
}

However, I'd given my poolOptions a global name because I thought that it would help with debugging if I created a rogue connection somewhere:

  val poolOptions = PoolOptions()
    .setMaxSize(16)
    .setIdleTimeout(15000)  // 15 second timeout
    .setConnectionTimeout(15000)  // 15 second timeout
    .setName("[globalName]")

I didn't think anything could go wrong with that since the documentation says:

used when the pool shared, otherwise ignored.

However, it turned out that this was the cause of my application freezing when it was doing a task that was very database heavy.