📄 index.xtp

📁 RESIN 3.2 最新源码
💻 XTP
字号:
<document><header><product>resin</product><type>tutorial</type><title>Connector</title><description><p>This is an advanced Connector tutorial for those interested in implementingConnector drivers or who just want to understand the inner workings.Connectors are a generalization of the JDBC DataSource, supportingpooling and transactions for any Connector following the interface.</p></description>    <tutorial-startpage>demo</tutorial-startpage></header><body><summary/><s1 title="Files in this tutorial"><deftable><tr><td><viewfile-link file="WEB-INF/web.xml"/>    </td><td>Configures the Connector</td></tr><tr><td><viewfile-link file="WEB-INF/classes/example/ConnectionImpl.java"/>    </td><td>User interface for the connection</td></tr><tr><td><viewfile-link file="WEB-INF/classes/example/ConnectionFactoryImpl.java"/>    </td><td>User interface for the connection factory</td></tr><tr><td><viewfile-link file="WEB-INF/classes/example/ManagedConnectionImpl.java"/>    </td><td>Driver (SPI) interface for the connection</td></tr><tr><td><viewfile-link file="WEB-INF/classes/example/ManagedConnectionFactoryImpl.java"/>    </td><td>Driver (SPI) interface for the connection factory</td></tr><tr><td><viewfile-link file="WEB-INF/classes/example/TestServlet.java"/>    </td><td>The demo servlet for the tutorial</td></tr></deftable></s1><s1 title="Overview"><glossary title="Connector">The driver's system of connections andfactories.</glossary><p>The connector architecture generalizes the pooling and transactioncapabilities of the JDBC DataSource, allowing other connections andeven user code to take advantage of pooling and transactions.  From auser's perspective, the system is simple: a factory creates connectionobjects.  The driver implementor's view is a bit more complex, ofcourse, but still only requires two extra classes: the server's viewof the factory and the server's view of the connection.</p><p>Understanding the connector system starts from the main class,the user connection, the user's view of the connection.</p><deftable><tr><td>user connection</td><td>User's view of the connection</td></tr><tr><td>user connection factory</td><td>User's view of the connection factory</td></tr><tr><td>managed connection</td><td>Resin's view of the connection</td></tr><tr><td>managed connection factory</td><td>Resin's view of the connection factory</td></tr></deftable><s2 title="User Connection"><p>The user connection is the main application interface.  Theconnector can use any API for the user connection.Typically, connections will at least have a <code>close()</code>method which will return the connection to the pool.</p><p>The user's connection, <code>ConnectionImpl</code> in the tutorial,has a similar function to the JDBC <code>Connection</code> class.It's the main object that applications will use.  Typically, it willbe used in a single threaded fashion and will be closed in a finallyblock to return the connection to the pool.</p><p>When the connection is returned to the pool, the user connection,<code>ConnectionImpl</code> is not reused.</p><p>The user connection and the user connection factory are the onlyinterfaces user code will see.  The user connection factory, likeJDBC's <code>DataSource</code> is responsible forcreating user connections.</p></s2><s2 title="User Connection Factory"><p>The user connection factory creates user connections.Users will generally get the user connection factory from JNDI duringinitialization and use it for all requests.  Each request will get anew user connection from the user connection factory.  In the example,the user connection factory is <code>ConnectionFactoryImpl</code>.</p><p>Like the user connection, the user connection factory may have anyAPI appropriate to the connector.  For example, a JDBC connector willuser the standard <code>DataSource</code>.</p><p>The user connection factory must be thread-safe, since multiplerequests may need new connections simultaneously.</p><p>When the user requests a new user connection from the userconnection factory, the user factory calls Resin's<code>ConnectionManager</code> interface to request a new connection.To create the new connection, Resin asks the driver'scontrolling class, the managed connection factory, for a newmanaged connection.</p></s2><s2 title="Managed Connection"><p>Each user connection uses an underlying managed connection to talkto the resource.  When the user is done with the connection, the<code>close()</code> method puts the managed connection back intoResin's pool for later reuse.  Once closed, the user connection isdiscarded.</p><p>The driver can choose whether most of the user connection logic isin the user connection or the managed connection.  If most of thelogic is in the user connection, the managed connection will typicallybe responsible connection resources, like a socket, but the userconnection may be responsible for the protocol.  Another architecturewill have the user connection act as a facade to the underlying codein the managed connection.  The architecture will depend on thedriver's needs.</p></s2><s2 title="Managed Connection Factory"><p>Resin's main interface to the connector is the managedconnection factory.  The managed connection factory is configured inthe web.xml using bean-style initialization.  Resin calls onthe managed connection factory for both the user connection factoryand to allocate new managed connections.</p></s2></s1><s1 title="Using the Connector"><p>Using the JCA connector follows the same pattern as for JDBC.The servlet looks up the <code>ConnectionFactory</code> inthe servlet's <code>init()</code> method and uses the connection in atry .. finally block.</p><p>As with JDBC, the user must put the <code>close()</code> in afinally block or the connection will leak.</p><example title="WEB-INF/classes/example/TestServlet.java">void init(){  ...    ic = new InitialConnection();    _factory =      (ConnectionFactoryImpl) ic.lookup("java:comp/env/factory");}void service(HttpServletRequest request,             HttpServletResponse response)  throws IOException, ServletException{  ConnectionImpl conn = null;  try {    conn = _factory.getConnection();    ...  } finally {    if (conn != null)      conn.close();  }}</example><p>The demo servlet just prints the <code>ConnectionFactory</code>and the <code>ConnectionImpl</code>.  As the following result show,each connection request uses a new <code>ConnectionImpl</code>, butkeeps using the same <code>ManagedConnectionImpl</code>.</p><results>Factory: ConnectionFactoryImpl[ManagedConnectionFactoryImpl[example]]Connection: ConnectionImpl[example-12-conn,ManagedConnectionImpl[example-0]]</results></s1><s1 title="Configuration"><p>As usual, Resin uses bean-style configuration for theconnector.  The example <code>ManagedConnectionFactoryImpl</code> hasa <code>setName</code> configuration method.  The &lt;init&gt; tag in theconfiguration file sets that value.  If needed, you can use JSP ELexpressions to assign the name value.</p><p>The <var>name</var> attribute is the JNDI name forthe user connection factor, in this case"java:comp/env/factory".  The &lt;type&gt; tag is the class name ofthe factory and the &lt;init&gt; section initializes the factory.</p><example title="WEB-INF/web.xml">&lt;resource name="factory"&gt;  &lt;type&gt;example.ManagedConnectionFactoryImpl&lt;/type&gt;  &lt;init&gt;    &lt;name&gt;example&lt;/name&gt;  &lt;/init&gt;&lt;/resource&gt;</example></s1><s1 title="Control Flow"><p>Since looking at the implementation methods can be a bit confusing,it's best to approach them as a set of method call chains.</p><s2 title="Installing the UserConnectionFactory"><p>During configuration, Resin needs to get the<code>UserConnectionFactory</code> from the<code>ManagedConnectionFactory</code> and store it in JNDI.</p><ol><li>Resin instantiates and configures the<code>ManagedConnectionFactory</code> from the configuration file.</li><li>Resin calls<code>ManagedConnectionFactory.createConnectionFactory</code> for theuser connection factory.  It passes along a<code>ConnectionManager</code> which points back to Resin.</li><li>Resin stores the user connection factory in JNDI.</li></ol><p>The <code>ConnectionManager</code> will be important in the nextstep to get a connection.</p></s2><s2 title="Getting a new Connection"><p>From the user's perspective, the main point of the connector isgetting a connection.  The user asks the user connection factory forthe request.</p><ol><li>The user calls the user connection factory's<code>getConnection</code> method.  This method would be specific tothe user connection factory's API.</li><li>The user connection factory calls Resin's<code>ConnectionManager.allocateConnection</code> method to ask for anew connection.</li><li>Resin checks the pool but it's empty, so needs to get a newconnection.</li><li>Resin calls the managed connection factory's<code>createManagedConnection</code> method to get a new managedconnection.</li><li>Resin registers itself as a listener forthe <code>ManagedConnection</code>, so it will know when theconnections close or have a fatal error.</li><li>Resin calls the managed connection's <code>getConnection</code>method to get a new user connection.</li><li>Resin finally returns the user connection to the user.</li></ol></s2><s2 title="Returning a Connection to the pool"><p>After the user is done with the connection, the finally block willclose the connection.  The connector takes the following steps to putthe connection into the pool:</p><ol><li>The user calls the connection's <code>close</code> method.  Thismethod is specific to each API, but <code>close</code> is a goodchoice.</li><li>The connection notifies the listeners in the managed connectionthat the connection has closed.  In the example,<code>ConnectionImpl</code> calls the<code>ManagedConnectionImpl.close()</code> method.</li><li>Since Resin is registered as a listener, the managed connectioncalls Resin's <code>connectionClosed</code> method.</li><li>Resin returns the managed connection to the pool and marks itidle, ready for the next request.</li></ol></s2><s2 title="Getting a Connection from the pool"><p>From the user's perspective this looks exactly like getting a newconnection does.  There's a bit more work for the managed connectionfactory, though.</p><ol><li>The user calls the user connection factory's<code>getConnection</code> method.  This method would be specific tothe user connection factory's API.</li><li>The user connection factory calls Resin's<code>ConnectionManager.allocateConnection</code> method to ask for anew connection.</li><li>Resin checks the pool and there are idle connections.  But Resinneeds to ask the managed connection factory if any can be used forthis request.</li><li>Resin calls the managed connection factory's<code>matchManagedConnections</code> with the idle managed connectionpool to see if any can be used.</li><li>If there's a valid managed connection in the pool, the managedconnection factory return it.</li><li>Resin then takes the managed connection from the pool.</li><li>Resin calls the managed connection's <code>getConnection</code>method to get a new user connection.</li><li>Resin returns the user connection to the user.</li></ol></s2></s1><s1 title="Compatibility"><p>Since this example uses the JCA API, the code is compatible acrossall application servers.  The configuration, of course, will bedifferent for each.  Many other applications will require generationof a .rar file and some additional XML files, although those should berelatively straightforward.</p></s1></body></document>
⌨️ 快捷键说明

复制代码 Ctrl + C
搜索代码 Ctrl + F
全屏模式 F11
切换主题 Ctrl + Shift + D
显示快捷键 ?
增大字号 Ctrl + =
减小字号 Ctrl + -