View Javadoc

1   /*
2    * $Id: Connectable.java 19191 2010-08-25 21:05:23Z tcarlson $
3    * --------------------------------------------------------------------------------------
4    * Copyright (c) MuleSoft, Inc.  All rights reserved.  http://www.mulesoft.com
5    *
6    * The software in this package is published under the terms of the CPAL v1.0
7    * license, a copy of which has been included with this distribution in the
8    * LICENSE.txt file.
9    */
10  
11  package org.mule.api.transport;
12  
13  import org.mule.api.lifecycle.Lifecycle;
14  import org.mule.api.retry.RetryContext;
15  
16  /**
17   * Interface for objects that should connect to a resource.
18   */
19  public interface Connectable extends Lifecycle
20  {
21  
22      /**
23       * Make the connection to the underlying transport. The fact that this object is
24       * connected or not should have no influence on the lifecycle, especially the
25       * start / stop state if applicable.
26       * 
27       * @throws Exception
28       */
29      void connect() throws Exception;
30  
31      /**
32       * Disconnect the from the underlying transport
33       * 
34       * @throws Exception
35       */
36      void disconnect() throws Exception;
37  
38      /**
39       * Determines if this object is connected or not
40       */
41      boolean isConnected();
42  
43      /**
44       * Returns a string identifying the underlying resource
45       */
46      String getConnectionDescription();
47  
48      /**
49       * Test whether the connector is able to connect to its resource(s).
50       * This will allow a retry policy to go into effect in the case of failure. Implementations must
51       * call either:
52       * <ul>
53       *  <li>{@link RetryContext#setOk()} when no problems found (or no validation required).
54       *  <li>{@link RetryContext#setFailed(Throwable)} with a root cause for a connection failure.
55       * </ul>
56       * Callers should then check for {@link RetryContext#isOk()}. The failure, if any, will be
57       * provided via the {@link RetryContext#getLastFailure()}.
58       * 
59       * @return same retry context with status info set and any failures populated
60       * @throws Exception if the connector fails to connect  @param retryContext
61       */
62      RetryContext validateConnection(RetryContext retryContext);
63  }