2: XGate Servlet

XGate is a WebMaker server component that handles requests from the browser, performs data-bindings and forwards requests to server controllers. XGate also sends responses back to the browser. In both directions, XGate has the ability to use plug-ins to intercept and alter behaviour based on your custom code. XGate can also act as a gateway to remote service invocations, including calls to SOAP and REST services. (Requires XML Controllers). The XGate configuration details reside in the deployment descriptor file of the Web application. If {webapps_location} is the web application deployment area of the Web server, the XML deployment descriptor of a {myapp} application can be found under {webapps_location}/{myapp}/WEB-INF/web.xml. An example web.xml file is shown below:

<?xml version="1.0" encoding="ISO-8859-1"?>
<!DOCTYPE web-app PUBLIC "-//Sun Microsystems, Inc.//DTD Web Application 2.3//EN"
    "http://java.sun.com/dtd/web-app_2_3.dtd">
<web-app>
    <servlet>
        <servlet-name>xgate</servlet-name>
        <servlet-class>com.hyfinity.xgate.HTTP2Java</servlet-class>
        <init-param>
            <param-name>morphyc</param-name>
            <!-- Sets the Morphyc configuration file to use for this application -->
            <param-value>c:/jprogramfiles/hyfinity/runtime/morphyc/helloworld_morphyc.xml</param-value>
        </init-param>
        <load-on-startup>10</load-on-startup>
    </servlet>
    <servlet-mapping>
        <servlet-name>xgate</servlet-name>
        <!-- Set all incoming requests to be handled by XGate.
             For an MVC application the mapping would be '*.do' to not pick up CSS, image, etc requests-->
        <url-pattern>/*</url-pattern>
    </servlet-mapping>
    <session-config>
        <session-timeout>30</session-timeout>
    </session-config>
</web-app>

                    

XGate also accepts a second configuration file stored in {webapps_location}/{myapp}/doc/xgate.xml. If this file is not present, a version will be generated the first time a Run Test or Publish operation is performed. If defined, this file can be accessed via the Include Local File options on the Files tab of Page Design, and then navigating to the relevant location. An example of this configuration file is below.

<?xml version="1.0" encoding="UTF-8"?>
<xgate xmlns:xg="http://www.hyfinity.com/xgate" xmlns:xfact="http://www.hyfinity.com/xfactory">
    <product>mvc</product>
    <plug-ins>
        <!--Turn on SXForms processing for binding HTTP Parameters into XML structure -->
        <sxforms mark_unbound="true" delete_bound="true">true</sxforms>
        <!--Ensure HTML output is returned to the browser -->
        <ensure_html_response>true</ensure_html_response>
        <!--Output the HTML 5 Doctype-->
        <output_doctype doctype_system="" doctype_public="">true</output_doctype>
        <!-- disable pre processing of soap requests.
             If this is enabled, then a transform can be applied to incoming SOAP requests to format them for
             processing as standard HTML parameter based requests.-->
        <soap_preprocessing>false</soap_preprocessing>
        <!-- If true, automatically set the Language control field based on the user's locale -->
        <set_locale>false</set_locale>
        <!-- If set to true, this enables the cookie handling functionality -->
        <process_cookies>false</process_cookies>
        <!-- Enables file upload support for this application. The two attributes are optional, and not provided by default.-->
        <file_upload upload_dir="c:\temp\uploads" plugin_class="com.example.MyFileUploadPlugin">true</file_upload>

        <!-- Define any custom plug-ins required -->
        <custom_plugins>
            <custom_plugin name="My Plug-in" runtime_instance="com.test.MyPlugin" priority="10"/>
        </custom_plugins>
    </plug-ins>
</xgate>
                    

This file provides control over a number of in-built features and the ability to define your own custom plug-ins. These plug-ins reside between the browser and server and allow interception and inspection of the data received from the browser, and the response being sent back to the browser. For example, a plug-in could be used to enforce custom security checks before allowing access to the controllers. See the next section for more details on writing custom plug-ins. Both of these configuration files are automatically set up when applications are published from the WebMaker Studio. You can change these files and place copies within the relevant locations under the webapp directory for your project in the repository. This ensures your changed files will be reused for future test and publish operations. XGate also makes use of other configuration files that are located within the doc directory within particular webapp structures, but these files should be managed automatically by the WebMaker Studio. You can learn more about XGate plug-ins on the WebMaker Forum. Search for "xgate". If the process_cookies setting in the xgate.xml configuration file is set to true, XGate will perform some automatic handling of browser cookies. Firstly it will provide a list of all of the cookies received from the client in the Control section of the message so that they can be easily accessed from your Controllers.

<eForm xmlns="http://www.hyfinity.com/mvc">
    <Control>
        ...
        <Cookies>
            <Cookie name="JSESSIONID" value="61EF3E000F8A491327BA7DEE7258FE66"/>
            <Cookie name="mycookie" value="cookievalue"/>
        </Cookies>
        ...
                    

Secondly, before returning the response to the client, any changes to ths Cookies fragment will be detected and processed. If the value attribute for a cookie has been updated, this new value will be sent to the browser. If a Cookie element is removed completely, then the cookie will also be removed from the browser. If a new Cookie element is inserted into this Control fragment, then the browser will be sent the new cookie. When creating a new cookie, there are a number of extra attributes that can be used if required to further configure the new cookie:

<Cookie name="NewCookie" value="123" comment="cookie comment" domain="mydomain.com" path="/myapp" maxAge="1800" secure="true" httpOnly="true" xmlns="http://www.hyfinity.com/mvc" /> 

Custom plug-ins allow you to write your own Java code to augment the standard functionality provided by the XGate Servlet. Each custom plug-in needs to implement the com.hyfinity.xgate.XGatePlugin interface, the JavaDoc for which is available here. This interface defines two methods that require implementation, processInput and processOutput. The first will be called on each incoming request to give you the option to manipulate the request before it is passed to server controllers for processing, whereas the second will be called with the response received from server controllers (usually HTML content) to perform any final manipulation before the response is returned to the browser. You can define as many custom plug-ins as you need by listing each one as a custom_plugin element in the xgate.xml file as shown below.

<xgate>
...
<plug-ins>
    ...
    <custom_plugins>
        <custom_plugin name="my plug-in" priority="10" runtime_instance="com.company.MyPlugin"/>
        <custom_plugin name="custom plug-in 2" priority="70" runtime_instance="com.company.MyPlugin2"/>
    </custom_plugins>
</plug-ins>
</xgate>
                    

The name attribute provides a friendly name for the plug-in that is output to the Debugger logs, the runtime_instance attribute provides the classname for your plug-in, and the priority configures the order in which the plug-ins will execute. Plug-ins with a lower priority number will be called first. All the in-built plug-ins that handle the data binding process, etc., have a fixed priority of 50. Therefore, if you add your custom plug-in with a priority less that this, the message it receives will generally be a flat list of parameters sent from the browser, whereas if you use a priority value over 50, the message will look like the structured XML you see in the various binding screens. If you need to return non-HTML content (e.g. to return a PDF file), you can do this from the processOutput method. You need to output your content to the response object directly, and then set the output document to null (output.setDocument(null)) to prevent XGate from attempting to return the normal content. Once you have written your plug-in you will need to ensure it is compiled successfully and available to your deployed/published application. One way to do this is to place your compiled classes/jar within the WEB-INF directory under the webapp directory for your project in the repository. All the jars needed to compile your code can be found in the <install_dir>/design/tomcat-design/common/lib directory. When you are trying to debug custom plug-ins, it is useful to switch the logging level to debug via the Test Settings menu option. You will then be able use the Debugger to see the state of the message before and after calling each plug-in. This is normally suppressed for applications during development.