Home | Printable Version
4.1: Debugger - Tracing application flow and debugging
WebMaker produces application logs, which can be configured for different modes of execution and the amount of logging information that is produced and parsed for viewing can be controlled using various settings. This can be very useful during development, testing and live operation. You can use the Test Settings - Debugging Log Details platform logging level from Warning to Debug, to view full details. The diagram below illustrates the main processing flow, which is discussed in more detail below: WebMaker Runtime Architecture
WebMaker Runtime Components and Request and Response stages:
Incoming 1 - Action Mapping. The runtime platform processing starts when theXGate servlet receives a request from a client browser or server. Upon receipt, XGate will attempt to map the requested action to a server Controller using the mapping.xml file. This file is located at webapps/doc and should be maintenance free for the majority of web applications. Incoming 2 - XGate Custom Plug-in. Once an action has been mapped, XGate will search for any Custom Plug-ins that may be defined. These are custom Java classes and are described in the xgate.xml file located at webapps/doc. If custom plug-ins are found then the incoming request message will be sent to the plug-ins. Once plug-ins have finished processing, the resulting message will be forwarded to the View Controller for onward processing. An example plug-in may call an LDAP server to obtain security credentials and provide this information as an XML fragment. This information can then be used within the Controllers to restrict access to remote services, validate against remote services, control access to page menus, etc. Incoming 3 - Binding. The next step binds the incoming name-value pairs to the XML instance documents. Incoming 4 - View Controller. This is the first native rules-based processing controller of the runtime platform and should be largely maintenance-free, although it has rules capabilities just like any other Controller and its behaviour can be modified if necessary. During the incoming request leg, the View controller inspects the incoming message to determine the target Controller name. It then uses this to forward the message to that controller for further processing. You may notice by this stage there is a default eForm wrapper that has been created by WebMaker. This is applied by XGate and should not require modification. This wrapper enables you to separate 'administrative' header information from the application data. Any information that could not be bound will appear in the /mvc:eForm/mvc:Control section. The other Fields indicate the action and the target Controller and also the name of the next Page. The Page name may be changed by the Controller on the response leg, depending on the execution outcome and which Page needs to be displayed. Incoming 5 - Controller Logic. Once the request message reaches the controller you can process the message using any number of native XML operations such as copying, deleting, validating, transforming, etc. You can also use the Invoke Service action to call remote services and other Controllers. For a full list of available operations please see the Rules Design Reference guide. Incoming 6 - Soap, Rest, Remote Service Security and HTTP Programming. WebMaker separates the business application from the technical plumbing required to connect together a SOA application. This includes the transport requirements for communicating with remote services via the XGate communications gateway. There may be occasions when you need more detailed control of the underlying HTTP communication. This can be achieved using an XGate HttpHeader control fragment to manipulate advanced elements of HTTP Headers. Please see the earlier section on Rest Based Services for more details. Incoming 7 - Access Services (including Proxy controllers) When a WSDL is parsed, WebMaker automatically sets up an Access Service for each of the services defined in the WSDL. Access services are controllers created in the Model layer that also wrap request messages, call remote services, process the responses and unwrap the responses, ready for processing on the outgoing response leg. The proxy service shown simply acts as a placeholder for the remote service address. This occurs when a controller is designated as a Remote Service Proxy in the Test Settings menu option dialogue (Please see Test Menu - Test Settings section below. Controllers defined as Remote Service proxies have no internal structure or rules capabilities. They simply become a URL endpoint configuration parameter at runtime. All pre and post processing for remote service calls should ideally be performed in the Controller and, if the change applies to all operations of the remote service such as the caching and submission of security tokens, then the Access Service rules can be modified. Outgoing 1 - Service Error Checking, Unwrapping, caching, etc. When a service call returns, it will typically be wrapped and may include information that needs to be sent back with subsequent requests, such as record ids and security tokens, etc. The Access Service controllers in the Model layer can be used to handle such tasks. By default, rules for Fault checking and message unwrapping are generated by WebMaker when WSDLs are imported. Outgoing 2 - Controller Logic This presents the opportunity for processing before the information is transformed for output to the next screen or other calls are made to other services. This is also the stage when you can set the page name for the next screen. This is the page name that will be used by the View Controller to locate the XSL transformation to generate the next page. At this stage you should also ensure that the XML instance document that was used for the Page Display Bindings is located in the right place to enable page transformation to perform the correct bindings and display the correct data on the HTML page. If the information is missing or in the wrong format then the screen will contain blank or incorrect data and structures. Outgoing 3 - View Agent In almost all cases this stage simply transforms the data returned by the Controller using the next Page name to create the next page. You can add generic rules here to redirect to an error page or perform logs, etc. if there are errors present. If a translation parameter was provided during the request then the WebMaker will look for translation files at this stage, to perform language translations. Outgoing 4 - XGate Custom Plug-in At this stage you should write the output part of Custom Plug-ins if you decided to use one. The response will be forwarded to the plug-in before being sent to the browser. An example plug-in at this stage may be written to simply amend the HTML DOC-TYPE for the page being returned.
The View Controller
The image below shows the default rules that form part of the View controller. The first rule is activated during the incoming request leg of the message flow. This is used to locate and forward the request to the appropriate target Controller. The second rule is activated on the outgoing response leg, which essentially transforms the message response from the controller to create the HTML page. The third rule is the same as the second, but accounts for language translations. The View controller is just like any other Controller, which means you can add your own rules here if required. For example, you may decide to check for an error fragment and respond with a different page if errors are found. This can be done by simply changing the page name to re-direct to an error page. View - Page Painter Rules
WebMaker eForm structure - Control and Data Blocks
In the earlier section on the View Controller you will notice a message fragment on the left, which is the default control data. This was captured during the incoming request leg of the journey. You should notice that the posted request information to the server has been wrapped within the /mvc:eForm/mvc:Data element. This is the default wrapper for the data, but can be changed as required. The /mvc:eForm/mvc:Control section of the message contains control information such as the name of the requested Controller, the next Page name, the requested action, etc. WebMaker will also place unbound form elements within this section. This may be because some bindings are invalid or designed intentionally to appear in the Control section. WebMaker Wrapper Within each controller you have full access to the wrapped information. The main information of interest typically is the payload contained within the /mvc:eForm/mvc:Data element. Once the message has flowed through the various controllers to the access service, it will be re-wrapped using a SOAP Wrapper by default. This is performed by transforming the contents of the /mvc:eForm/mvc:Data into /soap:Envelope/soap:Body. This transformation is achieved using file SOAP_Wrapper.xsl. You can modify this to suit your exact soap wrapping requirements. The reverse wrapping and unwrapping is performed during the outgoing response leg of the message flow. Essentially, the /mvc:eForm wrapper is used to wrap and provide a containing element for the unstructured data captured from the client pages and also to contain WebMaker domain-specific information during execution within the WebMaker Platform. The /soap:Envelope is used for SOAP and HTTP requests to remote services. These wrappers and the mappings between them can be altered, but should not be necessary is most cases. SOAP Wrapper
Debugging and tracing your application flow
The WebMaker Platform uses the same logging mechanism and Debugger application within development, user acceptance testing and production environments. The key differences between the types of deployment is determined by the settings of individual parameters for application configuration and logging options. WebMaker automatically logs message flows through an application to enable easier troubleshooting, during application design and execution. Example screen shot of the Dashboard log viewer Additional information about the Debugger in available within the Server Platform Administration section.
Testing Applications Run Service Tester