Loosely Coupled Transactor Server
Loosely Coupled Transactor ServerIntentProvide an asynchronous server-based solution primarily for clients that do not have .NET capabilities and for clients that do not wish to utilize the built-in asynchronous features of .NET and of the Web services proxy-generator tools that come with the framework. Asynchronous System Design ChallengesMany of you may have already had exposure to asynchronous-based development. If you have ever worked with Microsoft Message Queue Server, TIBCO, or any other asynchronous platform/API, you may already understand the benefits as well as the challenges that coincide with designing such a system. If you have worked with any of these or similar frameworks, you probably have realized that although they may provide the "async" plumbing, the design is still up to you. In fact, it is putting together a sound async design that is the most difficult. The technology behind an async model provides you only with the means of saving state, coordinating action, and possibly notifying the user during state changes. It is this plumbing that your model is designed on top of but it is the overall structure of the objects that are themselves independent of any technology. It seems as though developers initially think that as long as they have TIBCO or MSMQ, the async model will take care of itself. This is contrary to reality, and it is only when complicated async processes are implemented that those issues become plainly apparent. Some typical problems seen in async systems including the following:
Many systems have the luxury of being capable of correct design from inception. These systems can take into account the logic necessary to facilitate an async system and are thus better positioned to answer some of these issues above. Typically, however, it seems more common that existing synchronous (sync) systems are those that are targeted to receive async features. Usually, this is a result of poor performance from an existing application and the need to improve scalability. This is indeed more of a challenge. Now you must take existing business logic and retrofit it into an async environment. Most "blocking" or sync methods that must be designed to be async usually must first go through a redesign effort. Usually, you cannot simply put an async wrapper around a sync operation and expect everything to run as before. Not only do such systems undergo a form of technical redesign but they may also undergo a business flow redesign. The amount of refactoring depends on the order of events that must take place within the method logic and what dependencies it may have during execution. Determining these dependencies will help flush out those elements that require attention. When designing an async function, I suggest first answering some of the following questions:
The questions listed above mainly deal with three primary focus areas: state management, caller communication, and disconnected coordination/administration . State management simply deals with making information durable, whether that be saving data to a database or a file, or using a shared in-memory object. The goal of any asynchronous system is to release callers as soon as possible once the method is invoked so that they may go about their business. Doing so typically involves capturing enough information and continuing the processing of the transaction without blocking the caller. Once the transaction is complete, the response must be made available to the user, either by direct notification or by saving the response. Another use of state management is guaranteeing that what the caller has invoked will indeed eventually run to completion at some point, providing a transaction "status facility." This is typically where message queuing becomes useful by providing a responsive environment for users where once they fire off transactions, they can go about their work and still have the ability to see whether transactions are processing or have completed. The second area that must be thought out and designed is that of caller communication. This relates to how information will be presented to the user. The user can either be notified of server events directly or may poll the server, seeking status of a previously invoked method. Each has its advantages and disadvantages. Suffice it to say that employing notification is a convenient and efficient means of communication but is very technology-dependent and may not be a scalable option for your application (e.g., Internet applications). Polling is less efficient in that multiple calls may have to be made to assess the state of an async operation but it is beneficial in its simplicity and maintainability. You may also choose to provide notification for simple status messages and polling for large DataSets. This is something I have found to be quite successful as long as a notification and broadcast technology was deployed (e.g., TIBCO). Using MSMQ for broadcasts (one-to-many notifications) will be practical only in smaller environments. For larger environments, I recommend using a third-party message broadcast facility, rolling your own, or using a messaging server, such as Exchange. The third focus area in asynchronous design is that of disconnected coordination and administration. This relates to the first two in that typically, state must be held to help coordinate a multistep transaction. Also each step of the transaction may require user notification and interaction, depending on how complicated the operation may be. Async models become complicated when many steps require an ordered, coordinated action. You also have to address the freshness of the transaction being invoked. If failure occurs ”and it always does ”will the transaction be placed back into a queue? If it is, how long should it remain in the queue? Using a message queue system will aid in answering these quandaries through implementation but they are no substitute for a plan that is well thought out. This focus area will probably be the one that requires the most attention. It will also be the one that requires the most administration. For example, when utilizing a message queue environment for transactional multistep processes, there will be instances when transactions never complete. Unless there are administration processes and tools in place, a queue can quickly become overtaken by stale messages. This is where the K.I.S.S. (keep it simple stupid) principle really needs to be applied. By keeping your async model simple, you will ease your coordination pains in the future. I hope this won't scare you off from implementing async systems but it should serve as a slight warning. These systems shine in their ability to improve the scalability of most applications immediately and, to the delight of the user, no longer block users from performing other tasks while a transaction is running in the background. However, they can also become quite complicated and warrant significant design attention, especially when operations employ multiple steps or return large DataSets. The LCT Server presents a server-based asynchronous model that employs polling for those clients that do not have the technology for direct callbacks and/or notifications. It also provide a rather simple means of wrapping an existing synchronous system in an asynchronous cover that minimizes those async refactoring challenges mentioned previously. ProblemThe reason for even considering going async is simple ”the need for speed and scalability. There is also the added benefit of freeing up the user to do his or her work while a transaction may be running in the background. Not many of us like to see an hourglass while running a lengthy operation when we could be reading email. But for designers and system administrators, the real benefit is improved performance and scalability. With async invocations, the server is free from maintaining long-running connections with what could be hundreds of clients. This frees up memory and other valuable resources, which in turn improves scalability. With freed resources you now have improved performance. This is especially true for Web services applications. In fact, I highly recommend leveraging async processing whenever possible to improve your Web service performance overall. Much thought was placed in the area of async features as they relate to the .NET BCL, as well as the tools accompanying VS.NET. Instead of an afterthought as it is with some languages, .NET has built into the framework an asynchronous programming model. This programming model is seen in the networking features, such as .NET remoting, sockets, and as you'll see here, XML Web services. In fact, it couldn't be any easier to implement. Simply by instantiating the remote object (or more accurately, its proxy) and calling a remote method, you unblock the caller through async invocation. Microsoft has even taken the asynchronous model a step forward by standardizing the remote method names . For example, if an operation is called Foo() , then the remote async version of that will be called BeginFoo() and EndFoo() . With the aid of proxy generators such as WSDL.exe, you do not need to create specific async versions of methods or their signatures. The WSDL.exe tool or VS.NET will generate the async versions for you from the method signature or, more specifically , the WSDL output. Listing 7.12 shows both the Execute method sample from a Chained Service Factory (Chapter 4) and the sample wsdl.exe output generated from VS.NET. Listing 7.12 is a code snippet from the Chained Service Factory Web method called Execute . Listing 7.12 Code snippet from a Web Service Factory used by a typical LCT Server. public class ChainedServiceFactory : System.Web.Services.WebService { . . . [WebMethod] public DataSet Execute(DataSet dsData, string sService) { DataSet ds = new DataSet(); Facade oFacade = null; try { switch (sService) { case "Transactor": oFacade = (Facade) new TransactorFacade(); break; case "Report": oFacade = (Facade) new ReportFacade(); break; default: return ds; } } catch (Exception e) { throw new BaseException(. . .); } // invoke the factory method on the facade ds = oFacade.Execute(dsData); return ds; } } Next , the generated proxy code from VS.NET (the Begin and End methods are automatically generated for you): Listing 7.13 WSDL-generated output for the code snippet in Listing 7.12. public class ChainedServiceFactory : System.Web.Services.Protocols.SoapHttpClientProtocol { /// <remarks/> public ChainedServiceFactory() { . . . } /// <remarks/> [System.Web.Services.Protocols.SoapDocumentMethodAttribute(. . .)] public System.Data.DataSet Execute( System.Data.DataSet dsData, string sService) { object[] results = this.Invoke("Execute", new object[] { dsData, sService}); return ((System.Data.DataSet)(results[0])); } /// <remarks/> public System.IAsyncResult BeginExecute( System.Data.DataSet dsData, vstring sService, System.AsyncCallback callback, object asyncState) { return this.BeginInvoke("Execute", new object[] { dsData, sService}, callback, asyncState); } /// <remarks/> public System.Data.DataSet EndExecute( System.IAsyncResult asyncResult) { object[] results = this.EndInvoke(asyncResult); return ((System.Data.DataSet)(results[0])); } The same goes for other asynchronous features of the .NET BCL. To create a socket client, for instance, you call BeginConnect() instead of Connect() to make a remote socket connection. You can even build an asynchronous socket server using its built-in async methods. In fact, just by using Intellisense from within VS.NET, you can immediately see which class contains async support by looking for methods beginning with Begin or End . Whether an operation resides as part of a Web service, a socket server, or some other object residing in another app domain on the same machine, .NET gives you the power to call it asynchronously. Now that your mouth is watering with all of the great asynchronous features of .NET, there will be disappointments. Not every client implementation has the luxury of running .NET. Also there may be instances where changing client code becomes extremely prohibitive. For those cases, the LCT Server may aid in still providing an application with sorely desired async features. The LCT Server provides a server-side async wrapper around existing synchronous applications, and it does so rather unobtrusively. As stated earlier, it is difficult enough to design an async model, but it is considerably more difficult when having to retrofit an existing sync environment to provide async behavior. Does this mean that the LCT Server would never be used for a .NET client to .NET server application written from the ground up? No. In fact, due to its simplicity, it can be a good first design choice for providing async features with minimal headache for your users, as you will see. ForcesUse the LCT Server pattern when:
StructureThe structure begins when any client (does not have to be .NET) wishes to execute a synchronous operation a synchronously. The client first instantiates the TransactorService object instead of connecting to the original object. The client then calls Execute() on the TransactorService object, passing in any parameters required to send to the original synchronous operation (Figure 7.5). I highly recommend bundling parameters in a flexible, self-describing container, such as a .NET DataSet or XML. For information on how to send DataSets from non-.NET clients, please refer to Chapter 5. In fact, this pattern is a perfect opportunity to use another pattern covered in Chapter 4 ”Chained Service Factory. By combining the LCT Server with the Chained (or Unchained ) Service Factory, you can call any synchronous operation asynchronously. Figure 7.5. LCT Server generic class diagram. Once Execute() is called on the TransactorService, an identifier will be generated to identify the async job uniquely. This ID will be used to track and manage the async job once the caller is initially unblocked. The algorithm for generating the ID is up to you. You can use a GUID, an ID column from SQL Server, or as you'll see next, a database counter. The only other step before control is returned back to the caller is to save the job. This is where state management comes in. If you are using a formal messaging framework such as MSMQ, you could simply dump the parameterized message to a queue. How the state is held and what transport you use is really implementation-dependent. The only goal you have is to unblock your caller as soon as possible. This, of course, is the whole point of calling something in async fashion ”speed. Once the client is free, the server can normally do what it does to finish processing the request. Instead of using MSMQ, this pattern simply abstracts those operations common to all async job management. These operations can be found defined in the ITransactor interface and are implemented in the TransactorFacade. How they are implemented is again up to you. This pattern leverages off of the .NET Web service proxy generated from VS.NET to call the original operation. As shown in the class model, just before Transactor.Execute returns, the BeginExecute is called on the ExternalService. This will invoke the service asynchronously and register a callback method located in TransactorService. Once the operation is complete, the callback method, which is named appropriately enough ExternalCallback() , is invoked by .NET. Once invoked, the results of the ExternalService operation can be retrieved. Once retrieved, those results are then stored for later retrieval by the client. The client will use the return job ID from the initial Execute call as the lookup identifier for the both the status and the results of the operation. The LCT Server acts as an async delegate (of sorts) that simply delegates the operation payload but it does so asynchronously. The TransactorService acts as a client to the operation that the caller usually invokes synchronously. In fact, the role of the TransactorService is no different than any client. The only two differences in its role are that it acts as a proxy for the real client and drives the TransactorFacade. The TransactorFacade's role is simply to help manage state. ConsequencesThe LCT Server pattern has the following benefits and liabilities:
Participants
ImplementationOne of the primary benefits of this pattern is its ability to be seamlessly added to the existing application. This is especially true for clients that have not yet installed .NET at the desktop. For the Financial Server application, the LCT Server simply "wraps" the FinancialServiceFactory class and is treated as the ExternalService entity. Now the client must now call the TransactorService synchronously and pass identical information as though calling the FinancialServiceFactory (Figure 7.6). The following Visual Basic Service Client calls the Web service method Execute on the TransactorService as though it were the real FinancialServiceFactory, using identical parameters. The difference lies in the methods that may return result sets. All result sets will not be returned synchronously as before but through the invocation of the GetTransaction(), as explained earlier. Figure 7.6. LCT Server class diagram ”implementation example. Listing 7.14 shows a typical FinancialService non-.NET client (implemented in Visual Basic 6.0) calling the FinancialServiceFactory through the LCT Transactor Service: Listing 7.14 Visual Basic SOAP Toolkit client used for calling the LCT Server. Option Explicit Dim soapClient As MSSOAPLib.SoapClient set soapClient = CreateObject("MSSOAP.SoapClient") Dim oNodes As MSXML2.IXMLDOMNodeList Dim oDataSet As MSXML2.IXMLDOMNodeList On Error Resume Next . . . 'set up oDataSet Call soapClient.mssoapinit( "http://localhost/transactorservice.wsdl", "TransactorService") Set oNodes = soapClient.Execute(oDataSet) If Err <> 0 then Result = Result & "Err.Number=" & Err.Number Result = Result & "Err.Description=" & Err.Description Result = Result & "SoapClient.faultcode=" & sc.faultcode End If . . . 'process oNodes xml return dataset (optional) The Listing 7.14 VB code snippet is just that ”a snippet. Most unmanaged clients will most likely be more complex. The LCT server is just another Web service. Calling it from VB can either use the SOAP Toolkit's high-level API as shown in Listing 7.14, or for more control, the low-level API can be used. There are only three calls to be made to the LCT server. The first call invokes the Execute call to initiate the transaction. Once called, the remaining calls consist of any polling invocations and the final call to retrieve the results from the initial request. For those transactions that do not return data, these final two invocations are not necessary. As mentioned, one of the benefits of this pattern is its simplicity. The simpler the client is designed, the better. More complicated clients ”such as those that must contain a callback, use multithreading to mimic asynchronous behavior, or utilize a messaging system ”all add deployment configuration headaches . Placing more of the design complexity at the server level will increase a developer's control and provide the ability to make future changes in the asynchronous behavior much easier. Once called, the Transactor service receives the DataSet input parameters and immediately forwards them to the actual service. The only difference is that the LCT Server becomes a "client" of sorts with that external service, and it is here that the callback must be implemented. The callback, when called, completes the original transaction workflow by updating the status of the transaction from "pending" to "complete" (other status codes can be implemented if needed). The final activity performed by the callback is updating the transaction record with the result set of the external method. The external method, in this case, simply returns a set of records back, and it can contain any data as long as it is encapsulated in a DataSet. The result set is then directly saved to the database by calling TransactorFacade.UpdateTransaction(), as implemented in Listing 7.15. Listing 7.15 shows the main execution (Execute) call, the callback method, a method for checking the status of the transaction, and the final transaction result set retrieval method. Listing 7.15 LCT Server "plumbing" implementation. /// <summary> /// This is the driver web service for the loosely coupled /// /// transactor /// From this web service, another service can be called /// /// /// asynchronously /// and its status queried and eventually the transaction results /// returned /// </summary> public class TransactorService : System.Web.Services.WebService { . . . /// <summary> /// Executes a particular external service asynchronously, /// can be easily made to /// call chained or unchained service factory (chapter 4) /// to launch any external service /// </summary> [WebMethod] public long Execute() { ITransactor oTransactor = (ITransactor) new TransactorFacade(); long lTransactorId = 0; localhost.ExternalService oExtService = new localhost.ExternalService(); try { // generate a unique transactor id lTransactorId = oTransactor.GenerateTransactionId(); // insert the job into the job table and give // it a pending status STATUS = 1 oTransactor.CreateTransaction( lTransactorId, 1); // 1 for pending // simply delegate to the // InvokeTimeConsumingMethod call... // this can be any call including a // chainedservicefactory oExtService.TransactorHeaderValue = new localhost.TransactorHeader(); oExtService.TransactorHeaderValue.lTransactorId = lTransactorId; oExtService.BeginInvokeTimeConsumingMethod( new System.AsyncCallback( TransactorService. ExternalServiceCallback), oExtService); } catch (Exception e) { throw new BaseException( Utilities.BuildErrorMessage( "LCT Server Exception thrown", e.Message), true); } return lTransactorId; } /// <summary> /// Returns just the status of the original transaction /// </summary> [WebMethod] public int GetStatus(long lTransactorId) { ITransactor oTransactor = (ITransactor) new TransactorFacade(); int nStatus = 0; try { // insert the job into the job table and give // it a pending status STATUS = 1 nStatus = oTransactor.GetStatus(lTransactorId); } catch (Exception e) { throw new BaseException( Utilities.BuildErrorMessage( v "LCT Server Exception thrown", e.Message), true); } return nStatus; } /// <summary> /// Executes a particular external service asynchronously, /// can be easily made to /// call chained or unchained service factory (chapter 4) /// to launch any external service /// </summary> [WebMethod] public DataSet GetTransaction(long lTransactorId) { ITransactor oTransactor = (ITransactor) new TransactorFacade(); DataSet ds = null; try { // insert the job into the job table and give // it a pending status STATUS = 1 ds = oTransactor.GetTransaction(lTransactorId); } catch (Exception e) { throw new BaseException( Utilities.BuildErrorMessage( "LCT Server Exception thrown", e.Message), true); } return ds; } /// <summary> /// Asynchronous Callback method for async ops /// </summary> /// <param name="ar"></param> public static void ExternalServiceCallback(IAsyncResult ar) { DataSet dsOriginal = new DataSet(); ITransactor oTransactor = (ITransactor) new TransactorFacade(); try { // Obtains return value from the delegate call // using EndInvoke. localhost.ExternalService oExtService = (localhost.ExternalService)ar.AsyncState; dsOriginal = oExtService.EndInvokeTimeConsumingMethod(ar); // update the transaction with a success (==2) // and the results of the original transaction if (dsOriginal != null) voTransactor.UpdateTransaction( oExtService.TransactorHeaderValue. lTransactorId, 2, dsOriginal); } catch(Exception e) { throw new BaseException( Utilities.BuildErrorMessage( "LCTServer Exception thrown", e.Message), true); } } } Let's start with Execute(). This is the first method called by the client. The Execute method initially instantiates the external service and later uses its asynchronous interface to invoke its own "contract" method. The external service in this case is another Web service but, as mentioned, can also come in the form of a .NET remoting call. Another Web service was used for simplicity and because the code was already written from the Web Service Factory (Chapter 4). The Web Service Factory Method is named InvokeTimeConsumingMethod and is leveraged and invoked through a single call into that external Web service. This call is delegated directly from the Transactor's Execute call, making this pattern relatively simple to implement. You'll notice that the external service method is actually indirectly called through the Begin version of the call, as generated by the Web service proxy using Visual Studio .NET. Just before calling the asynchronous factory, however, a transaction ID is generated, and a record is created into the database. The transaction ID generation uses a stored-procedure to generate the ID and SQL/ADO.NET to insert the new record in the database, as well as to update the status. The new database record is given a "pending" status code to provide the means by which the client can now track the status of the transaction. Most of the heavy lifting , such as driving the transaction ID generation and the transaction record creation, is done by the TransactorFacade class and its methods. This code is shown in Listing 5.15.
Listing 7.16 Sample functional implementation drive by the LCT Server. /// <summary> /// Main driver for all async (LCT) transaction operations /// </summary> public class TransactorFacade : ITransactor { private string m_sConnectionString = string.Empty; public TransactorFacade() { // for SQL Server Test m_sConnectionString = "Integrated Security=SSPI;" + "Initial Catalog=PatternsDotNet;" + "Data Source=DEV06;"; } /// <summary> /// Calls the appropriate stored proc to increment a db /// count and return it /// </summary> /// <returns></returns> public long GenerateTransactionId() { SqlConnection cn = null; StringBuilder sbExecSQL = null; SqlCommand oCommand = null; long lTransactionId = 0; try { sbExecSQL = new StringBuilder( "exec sp_DNPatternsIncCounter"); sbExecSQL.Append(" 'JOB_ID', 1"); // make the connection cn = new SqlConnection(); cn.ConnectionString = m_sConnectionString; cn.Open(); // call the storeproc sp_DNPatternsIncCounter if (cn.State == ConnectionState.Open ) { oCommand = new SqlCommand( sbExecSQL.ToString(), cn); lTransactionId = (long)oCommand.ExecuteScalar(); } } catch (Exception e) { throw new BaseException( Utilities.BuildErrorMessage( "General Exception thrown", e.Message), false); } finally { cn.Close(); } return lTransactionId; } /// <summary> /// This creates a new transaction /// as part of a transaction table (uses the specified /// transactor id) /// </summary> /// <param name="lTransactorId"></param> /// <param name="nStatus"></param> /// <returns></returns> public DataSet CreateTransaction(long lTransactorId, int nStatus) { DataTable oTable = new DataTable(); SqlParameter oParam = null; string sSelectText = string.Empty; SqlConnection cn = null; DataSet ds = null; SqlDataAdapter da = null; try { // make the connection cn = new SqlConnection(); cn.ConnectionString = m_sConnectionString; cn.Open(); if (cn.State == ConnectionState.Open ) { // build the sql statement and prepare // the dataset da = new SqlDataAdapter( "SELECT * FROM JOB", cn); ds = new DataSet("JOB"); da.Fill(ds, "JOB"); // prepare a data adapter with insert // statement string sInsertCommand = "INSERT INTO JOB (JOB_ID, STATUS) VALUES (@JOB_ID, @STATUS)"; da.InsertCommand = new SqlCommand(sInsertCommand, cn); // bind parms to insert oParam = new SqlParameter("@JOB_ID", SqlDbType.Int); oParam.SourceColumn = "JOB_ID"; oParam.SourceVersion = DataRowVersion.Current; da.InsertCommand.Parameters.Add(oParam); oParam = new SqlParameter("@STATUS", SqlDbType.Int); oParam.SourceColumn = "STATUS"; oParam.SourceVersion = DataRowVersion.Current; da.InsertCommand.Parameters.Add(oParam); oTable = ds.Tables["JOB"]; if (oTable != null) { // insert the new row DataRow oNewRow = oTable.NewRow(); oNewRow["JOB_ID"] = lTransactorId; oNewRow["STATUS"] = nStatus; oTable.Rows.Add(oNewRow); // save it to the database da.Update(ds, "JOB"); } else throw new BaseException( Utilities.BuildErrorMessage( "Inserting Job Failed", "Table object was null"), false); } } catch (Exception e) { throw new BaseException( Utilities.BuildErrorMessage( "General Exception thrown", e.Message), false); } finally { da.Dispose(); cn.Close(); } return ds; } /// <summary> /// Updates the transaction with the dataset results /// of any returned external call /// </summary> /// <param name="lTransactorId"></param> /// <param name="nStatus"></param> /// <returns></returns> public DataSet UpdateTransaction(long lTransactorId, int nStatus, DataSet dsOriginal) { DataTable oTable = new DataTable(); SqlParameter oParam = null; string sSelectText = string.Empty; SqlConnection cn = null; SqlDataAdapter da = null; DataRow oRow = null; DataSet dsJob = null; try { // make the connection cn = new SqlConnection(); cn.ConnectionString = m_sConnectionString; cn.Open(); if (cn.State == ConnectionState.Open ) { // build the sql statement and prepare // the dataset da = new SqlDataAdapter( new StringBuilder( "SELECT * FROM JOB WHERE JOB_ID = ") .Append(lTransactorId).ToString(), cn); dsJob = new DataSet("JOB"); da.Fill(dsJob, "JOB"); // build the update sql command da.UpdateCommand = new SqlCommand( new StringBuilder( "UPDATE JOB SET STATUS = @STATUS, DATA_SCHEMA = @DATA_SCHEMA, DATA = @DATA WHERE JOB_ID = @JOB_ID") .ToString(), cn); // bind the insert parameters oParam = new SqlParameter( "@STATUS", SqlDbType.Int); oParam.SourceColumn = "STATUS"; oParam.SourceVersion = DataRowVersion.Current; da.UpdateCommand.Parameters.Add(oParam); oParam = new SqlParameter( "@DATA_SCHEMA", SqlDbType.Image); oParam.SourceColumn = "DATA_SCHEMA"; voParam.SourceVersion = DataRowVersion.Current; da.UpdateCommand.Parameters.Add(oParam); oParam = new SqlParameter( "@DATA", SqlDbType.Image); oParam.SourceColumn = "DATA"; oParam.SourceVersion = DataRowVersion.Current; da.UpdateCommand.Parameters.Add(oParam); oParam = new SqlParameter("@JOB_ID", SqlDbType.Int); oParam.SourceColumn = "JOB_ID"; oParam.SourceVersion = DataRowVersion.Current; da.UpdateCommand.Parameters.Add(oParam); da.Fill(dsJob, "JOB"); // grab the table so we can update each // field as bound by the parameters oTable = dsJob.Tables["JOB"]; if (oTable != null) { // should be first and only row // found oRow = oTable.Rows[0]; if (oRow != null) { // insert the new row oRow["STATUS"] = nStatus; if (dsJob != null) { oRow["DATA_SCHEMA"] = Utilities.ToByteArray( DsOriginal .GetXmlSchema()); oRow["DATA"] = Utilities.ToByteArray( dsOriginal.GetXml()); } // save it to the database da.Update(dsJob, "JOB"); } else throw new BaseException(...); } else throw new BaseException(. . .); } } catch (Exception e) { throw new BaseException(. . .); } finally { da.Dispose(); cn.Close(); } return dsJob; } /// <summary> /// This will regenerate the original DataSet from the /// stored schema and data as xml in the job table /// </summary> /// <param name="dsJob"></param> /// <returns></returns> public DataSet ExtractOriginalData(DataSet dsJob) { DataSet dsOriginal = new DataSet("OriginalData"); string sSchema = null; string sData = null; try { // first convert byte array to string if (dsJob != null) { sSchema = Utilities.FromByteArray( (byte [])dsJob.Tables["JOB"] .Rows[0]["DATA_SCHEMA"]); sData = Utilities.FromByteArray( (byte [])dsJob.Tables["JOB"] .Rows[0]["DATA"]); dsOriginal.ReadXmlSchema( new StringReader(sSchema)); dsOriginal.ReadXml( new StringReader(sData)); } } catch (Exception ex) { throw new BaseException(. . .); } return dsOriginal; } /// <summary> /// Returns the transaction as a dataset /// for the transactor id /// </summary> /// <param name="lTransactorId"></param> /// <returns></returns> public DataSet GetTransaction(long lTransactorId) { string sSelectText = string.Empty; SqlConnection cn = null; SqlDataAdapter da = null; DataSet ds = null; DataSet dsOriginal = null; try { // make the connection cn = new SqlConnection(); cn.ConnectionString = m_sConnectionString; cn.Open(); if (cn.State == ConnectionState.Open ) { // build the sql statement and prepare // the dataset da = new SqlDataAdapter( new StringBuilder( "SELECT * FROM JOB WHERE JOB_ID = ") .Append(lTransactorId) .ToString(), cn); ds = new DataSet("JOB"); da.Fill(ds, "JOB"); // just so we can see the stored bytes // array as returned xml data dsOriginal = ExtractOriginalData(ds); } } catch (Exception e) { throw new BaseException(. . .); } finally { da.Dispose(); cn.Close(); } return dsOriginal; } /// <summary> /// Returns the status of the transaction /// </summary> /// <param name="lTransactorId"></param> /// <returns></returns> public int GetStatus(long lTransactorId) { string sSelectText = string.Empty; SqlConnection cn = null; SqlDataAdapter da = null; DataSet ds = null; int nStatus = 0; try { // make the connection cn = new SqlConnection(); cn.ConnectionString = m_sConnectionString; cn.Open(); if (cn.State == ConnectionState.Open ) { // build the sql statement and prepare // the dataset da = new SqlDataAdapter( new StringBuilder( "SELECT * FROM JOB WHERE JOB_ID = ") .Append(lTransactorId).ToString(), cn); ds = new DataSet("JOB"); da.Fill(ds, "JOB"); // just so we can see the stored bytes // array as returned xml data nStatus = (int)ds.Tables["JOB"] .Rows[0]["STATUS"]; } } catch (Exception e) { throw new BaseException(. . .); } finally { da.Dispose(); cn.Close(); } return nStatus; } } By placing the logic in this fa §ade, you have the obvious advantage of directly calling that class without going through the Web service (see Web Service Fa §ade pattern in Chapter 4). Each method in this TransactorFacade should be relatively self-explanatory. Each implements one of the ITransactor interface methods and makes up the "heart" of the pattern. UpdateTransaction() requires the most explanation because this is the method that is called by the Transactor Service callback when the asynchronous external service has completed. The two mains items that are updated are the status and the result set that was returned from the original external service call. The dataset is strongly leveraged here in that both the instance data from the data and the schema are stored. Each is stored in its own field and allows any data to be stored; the schema can then be retrieved at any time, along with the record. Both the instance data and the schema are stored as "image" fields in SQL Server. If using Oracle, BLOBS could also be used. To store each field, the DataSet XML contents are first converted to a byte array and directly saved using ADO.NET. For more details on using this form of data storage, please refer to Chapter 5 on persistence-tier patterns. The only other method needing explanation is ExtractOriginalData(). This is a helper method used once GetTransaction() is called on the TransactorService, and the database contents are then returned as a complete DataSet. Like its name, this pattern provides the implementer with a lot of flexibility in the manner in which it is implemented. Using several design variances, it can have many uses and can even function from server-to-server invocation, as well as client to server. It also represents an assembly of several best practices and patterns presented in this book. When it comes to providing any asynchronous solution, the model to live by is "the simpler, the better," and I hope this pattern delivers on that premise .  |
EAN: 2147483647
Pages: 70