Package org.jenkinsci.plugins.vsphere.tools

Class VSphereConnectionPool

java.lang.Object

org.jenkinsci.plugins.vsphere.tools.VSphereConnectionPool

public class VSphereConnectionPool
extends Object

Maintains a single long-lived vSphere session for one vSphereCloud instance, eliminating the per-operation login/logout overhead that occurs when every API call creates and destroys its own session.

Caller contract:

1. Obtain the shared connection via acquire().
2. Use it normally - all public VSphere methods work as usual.
3. Call VSphere.disconnect() exactly once when done. For pooled connections this releases the borrow back to the pool (see release()) rather than logging out directly; the pool controls the real session lifecycle and defers disconnecting an orphaned pool until every outstanding borrow is released.

Background maintenance:

• Health check - if healthCheckIntervalSecs > 0, a daemon thread periodically issues a lightweight currentTime() call and reconnects automatically on failure.
• Session age limit - if sessionMaxAgeSecs > 0, a one-shot timer is armed for the exact moment the session reaches that age, at which point it is proactively restarted (also re-checked defensively on the next acquire() call) - unless idleTimeoutSecs > 0 and no consumer has acquired the session since it was established, in which case it is disconnected instead of restarted, deferring to the idle policy. Without this, a sessionMaxAgeSecs smaller than idleTimeoutSecs would otherwise reconnect an unused session forever, since each reconnect also resets the idle clock and the idle timeout would never get a chance to win.
• Use-count limit - if sessionMaxUses > 0, the session is restarted on the next acquire() once that many acquisitions have been made.
• Idle timeout - if idleTimeoutSecs > 0, a one-shot timer is armed for the exact moment the connection has gone unused for that many seconds, at which point it is disconnected (and lazily reconnected on the next acquire()). The timer is re-armed on every acquire().

Session age and idle timeout are enforced by dedicated one-shot alarms rather than periodic polling, so they fire at (approximately) the exact configured deadline instead of some time after it.

A value of 0 disables the corresponding feature.

Thread-safe. All mutable state is guarded by this.

Constructor Summary

Constructors

Constructor	Description
VSphereConnectionPool(VSphereConnectionConfig config, int healthCheckIntervalSecs, int sessionMaxAgeSecs, int sessionMaxUses, int idleTimeoutSecs)
VSphereConnectionPool(VSphereConnectionConfig config, Cloud owner, int healthCheckIntervalSecs, int sessionMaxAgeSecs, int sessionMaxUses, int idleTimeoutSecs)

Method Summary

Modifier and Type	Method	Description
VSphere	acquire()	Returns the pooled VSphere connection, creating or restarting it if necessary.
void	shutdown()	Shuts down all background threads and, unless the connection is still borrowed by an in-flight caller (see acquire()/release()), disconnects the current session immediately.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Details

VSphereConnectionPool

public VSphereConnectionPool(@NonNull
 VSphereConnectionConfig config,
 int healthCheckIntervalSecs,
 int sessionMaxAgeSecs,
 int sessionMaxUses,
 int idleTimeoutSecs)

VSphereConnectionPool

public VSphereConnectionPool(@NonNull
 VSphereConnectionConfig config,
 @CheckForNull
 Cloud owner,
 int healthCheckIntervalSecs,
 int sessionMaxAgeSecs,
 int sessionMaxUses,
 int idleTimeoutSecs)

Parameters:

owner - the Cloud this pool belongs to, used only so that VSphereConnectionPoolRegistry can detect and shut down pools left behind by a cloud instance that was replaced by reconfiguration (e.g. saving the Jenkins global config). May be null (e.g. in tests), in which case this pool is never auto-reaped as an orphan.

Method Details

acquire

public VSphere acquire()
                throws VSphereException

Returns the pooled VSphere connection, creating or restarting it if necessary. The returned instance is marked as pooled so that callers' VSphere.disconnect() calls release it back to this pool instead of logging out directly. Every acquire() must eventually be matched by exactly one VSphere.disconnect() call on the returned instance, so that shutdown() can tell when it is safe to actually tear down the session - see release().

Throws:

VSphereException - if establishing the session fails.

shutdown

public void shutdown()

Shuts down all background threads and, unless the connection is still borrowed by an in-flight caller (see acquire()/release()), disconnects the current session immediately. If it is still borrowed, the actual disconnect is deferred until the last borrower releases it, so an in-flight vCenter operation (e.g. a build step that started before this pool's owning cloud was replaced) is not cut off mid-call. After this call the pool must not be used to acquire() further connections.