+ * Implementations of this interface are expected to be thread-safe in the sense + * that integrity of the host list is maintained even if multiple threads call + * multiple methods in this interface concurrently. + *
+ * This interface is not intended to be implemented by clients. + *
*/ - public interface ISystemHostPool extends IRSEPersistableContainer { /** - * Return the system profile that owns this connection pool + * Return the system profile that owns this connection pool. + * @return the system profile that owns this connection pool. */ public ISystemProfile getSystemProfile(); /** + * Return the name of this host pool. + * @return The value of the Name attribute. + */ + String getName(); + + /** * Rename this connection pool. + * @param newName the new name for this connection pool. */ public void renameHostPool(String newName); /** - * Return array of connections in this pool + * Return array of connections in this pool. + * + * The returned array is a copy of the internal connection list. Modifications by + * clients will not affect the internal list of connections, but modifications to + * the array elements will affect the actual IHost objects maintained in the list. + * + * @return array of connections in this pool. */ public IHost[] getHosts(); @@ -54,9 +68,10 @@ * @param systemType system type matching one of the system types * defined via the systemTypes extension point. * @param aliasName unique connection name. - * @param hostName ip name of host. - * @return SystemConnection object, or null if it failed to create + * @param hostName IP name or address of the host. + * @return IHost object, or null if it failed to create * because the aliasName is not unique. All other errors throw an exception. + * @throws Exception if something goes wrong creating the connection. */ public IHost createHost(IRSESystemType systemType, String aliasName, String hostName) throws Exception; @@ -67,10 +82,11 @@ * @param systemType system type matching one of the system types * defined via the systemTypes extension point. * @param aliasName unique connection name. - * @param hostName ip name of host. + * @param hostName IP name or address of the host. * @param description optional description of the connection. Can be null. - * @return SystemConnection object, or null if it failed to create + * @return IHost object, ornull if it failed to create
* because the aliasName is not unique. All other errors throw an exception.
+ * @throws Exception if something goes wrong creating the connection.
*/
public IHost createHost(IRSESystemType systemType, String aliasName, String hostName, String description) throws Exception;
@@ -81,13 +97,14 @@
* @param systemType system type matching one of the system types
* defined via the systemTypes extension point.
* @param aliasName unique connection name.
- * @param hostName ip name of host.
+ * @param hostName IP name or address of the host.
* @param description optional description of the connection. Can be null.
* @param defaultUserId userId to use as the default for the subsystems.
* @param defaultUserIdLocation where to set the given default user Id. See IRSEUserIdConstants for values.
- * @return SystemConnection object, or null if it failed to create
+ * @return IHost object, or null if it failed to create
* because the aliasName is not unique. All other errors throw an exception.
* @see IRSEUserIdConstants
+ * @throws Exception if something goes wrong creating the connection.
*/
public IHost createHost(IRSESystemType systemType, String aliasName, String hostName, String description, String defaultUserId, int defaultUserIdLocation) throws Exception;
@@ -99,30 +116,41 @@
*
- * @param conn SystemConnection to be updated
+ * @param conn IHost to be updated
* @param systemType system type matching one of the system types
* defined via the systemType extension point.
* @param aliasName unique connection name.
- * @param hostName ip name of host.
+ * @param hostName IP name or address of the host.
* @param description optional description of the connection. Can be null.
* @param defaultUserId userId to use as the default for the subsystems.
* @param defaultUserIdLocation where to set the given default user Id from IRSEUserIdConstants.
* @see IRSEUserIdConstants
+ * @throws Exception if something goes wrong updating the connection.
*/
public void updateHost(IHost conn, IRSESystemType systemType, String aliasName, String hostName, String description, String defaultUserId, int defaultUserIdLocation) throws Exception;
- /**
- * Return a connection given its name.
- */
+ /**
+ * Return a connection object, given its alias name.
+ *
+ * Can be used to test if an alias name is already used (non-null return).
+ *
+ * @param aliasName unique aliasName (case insensitive) to search on.
+ * @return IHost object with unique aliasName, or null if
+ * no connection object with this name exists.
+ */
public IHost getHost(String aliasName);
/**
- * Return the connection at the given zero-based offset
+ * Return the connection at the given zero-based offset.
+ * @param pos zero-based offset of requested connection in the connection list.
+ * @return IHost object requested.
*/
public IHost getHost(int pos);
/**
* Add a new connection to the list.
+ * @param conn Connection to add. Must not be null.
+ * @return true if the new connection was added successfully, false otherwise.
*/
public boolean addHost(IHost conn);
@@ -135,7 +163,7 @@
*
- * @param conn SystemConnection object to remove + * @param conn IHost object to remove */ public void deleteHost(IHost conn); @@ -147,65 +175,64 @@ *
null as result) if this is not unique.
+ * @return the cloned host, or null if the new alias name was not unique.
+ * @throws Exception if anything goes wrong during cloning.
*/
public IHost cloneHost(ISystemHostPool targetPool, IHost conn, String aliasName) throws Exception;
/**
* Move existing connections a given number of positions in the same pool.
- * If the delta is negative, they are all moved up by the given amount. If
- * positive, they are all moved down by the given amount.+ * If the delta is negative, they are all moved up (left) by the given amount. If + * positive, they are all moved down (right) by the given amount.
*