Introduction

Walkthrough

<authentication mode="Forms"/>
<authorization>
      <deny users="?"/>
      <allow users="*"/>
</authorization>

<style type="text/css">
        .modalBackground {
            background-color: Gray;
            filter: alpha(opacity=30);
            opacity: 0.3;}
        .modalPopup {
            width: 250px;
            height: 150px;
            background-color: #076DAB;
            color: #FFFFFF;
            border-color: #000000;
            border-width: 1px;
            border-style: solid;
            text-align: center;
            cursor: move;
            font-size: medium;}
</style>

<cc1:ModalPopupExtender ID="LoginStatus1_ModalPopupExtender" 
runat="server" 
DynamicServicePath=""
Enabled="True" 
TargetControlID="LoginStatus1" 
BackgroundCssClass="modalBackground"
PopupControlID="Panel1">
</cc1:ModalPopupExtender>

<asp:Panel ID="Panel1" runat="server" CssClass="modalPopup" Style="display: none">

<asp:Login ID="Login1" 
runat="server" 
DestinationPageUrl="~/Login.aspx" 
DisplayRememberMe="False"
TitleText="" 
UserNameLabelText="Employee:" 
OnAuthenticate="Login1_Authenticate"
FailureText="Incorrect employee or password" 
Width="100%" 
VisibleWhenLoggedIn="False">
</asp:Login>

<asp:Button  ID="btnCancel" runat="server" OnClick="btnCancel_Click" Text="Cancel" />

using System;
using System.Web.UI.WebControls;
using System.Web.Security;
 
public partial class MasterPage : System.Web.UI.MasterPage
{
    protected void Page_Load(object sender, EventArgs e)
    {
        // Popup dialog won't fire if user is already in.
        if (Request.IsAuthenticated)
        {
            LoginStatus1_ModalPopupExtender.Enabled = false;
        }
        else
        {
            LoginStatus1_ModalPopupExtender.Enabled = true;
        }
    }
 
 
    // Authenticate user's crendential if Login button is clicked.
    protected void Login1_Authenticate(object sender, AuthenticateEventArgs e)
    {
        // You can add authentication logic here.
        e.Authenticated = ((Login1.UserName == "test") && 
            (Login1.Password == "test"));
 
 
        // Continue to display the popup dialog and failure text if login failed.
        if (!e.Authenticated)
        {
            LoginStatus1_ModalPopupExtender.Show();
        }
    }
 
    // Hide the popup dialog if Cancel button is clicked.
    protected void btnCancel_Click(object sender, EventArgs e)
    {
        LoginStatus1_ModalPopupExtender.Hide();
    }
}

Summary

According to me, FCKeditor is the coolest HTML editor. It is very popular among web developers because of its rich set of useful features. It's also compatible with ASP.NET. But it has some issues with the ASP.NET page theme. When uploading files or images through the editor, it displays an wired XML parse error stating that "Using themed CSS files requires a header control on the page."

Solution

UserFilesPath = Page.ResolveUrl("~/userfiles/");

<configuration>
<appSettings/>
<connectionStrings/>
<system.web>
<pages styleSheetTheme="" theme=""> </pages>
</system.web>
</configuration>

For building scalable and high-performance Web based applications, ASP.NET provides a feature called data caching. Data caching enables programmatic storing of frequently accessed data objects in memory. This feature can be extended to vastly improve performance for ASP.NET applications that query data stored in an Oracle database. This article describes a strategy for caching Oracle database data in ASP.NET Web applications deployed using a Web Farm environment. This technique enables caching of frequently accessed Oracle database data in memory rather than making frequent database calls to retrieve the data. This helps to avoid unnecessary roundtrips to the Oracle database server. Further the article proposes an implementation for maintaining the cached data so it is always in sync with the corresponding data in the Oracle database.

Data Caching in ASP.NET

Data Caching in ASP.NET is facilitated via the Cache class and the CacheDependency class in the System.Web.Caching namespace. The Cache class provides methods for inserting data and retrieving data from the cache. The CacheDependency class enables dependencies to be specified for the data items placed in the cache. An expiration policy for an item can be specified when we add it to the cache using the Insert method or Add method. We can define the life span for an item in the cache by using the absoluteExpiration parameter in the Insert method. This parameter allows one to specify the exact datetime that the corresponding data item will expire. One can also use the slidingExpiration parameter, specifying the elapsed time before the item will expire based on the time it was accessed. Once the item expires, it is removed from the cache. Attempts to access it will return a null value unless the item is added to the Cache again.

Specifying Dependencies for Cache

ASP.NET allows us to define the dependency of a cached item based on an external file, a directory, or another cached item. These are described as file dependencies and key dependencies. If a dependency changes, the cached item gets automatically invalidated and removed from the cache. We can use this approach to delete items from the cache when the corresponding data source changes. For example, if we write an application that retrieves data from an XML file and displays it in a grid, we can store the data from the file in the Cache and specify a Cache dependency on the XML file. When the XML file is updated, the data item gets removed from the cache. When this event occurs, the application reads the XML file again, and the latest copy of the data item is inserted into the cache again. Further, callback event handlers can be specified as a listener for getting notified when the cache item gets deleted from the cache. This eliminates the need to continuously poll the cache to determine whether the data item has been invalidated.

ASP.NET Cache Dependency on Oracle Database

Let us consider a scenario where data is stored in the Oracle database and accessed by an ASP.NET application using ADO.NET. Furthermore, let us assume that the data in the database table(s) is generally static but accessed frequently by the Web application. In a nutshell, there are very few DML operations on the table but lots of Selects on the data. Such a scenario is ideal for data caching. But unfortunately, ASP.NET does not allow a dependency to be specified whereby a cache item is dependent on data stored in a database table. Furthermore, in real world Web based systems, the Web server and the Oracle database server could be potentially running on different machines, making this cache invalidation process more challenging. Also most Web-based applications are deployed using Web farms with instances of the same application running on multiple Web servers for load balancing. This scenario makes the database caching problem slightly more complex.

For exploring the solution to the above problem, let's put together a sample Web application to illustrate how it can be implemented. For our example, we use ASP.NET application implemented in VB .Net communicating with the Oracle 9i database using Oracle Data Provider for .NET (ODP).

In this example, consider a table named Employee in the Oracle database. We define a trigger for insert, update and delete operations on the Employee table. This trigger calls a PL/SQL function that serves as a wrapper for a Java stored procedure. This Java stored procedure in turn will be responsible for updating the Cache dependency file.

ASP.NET Tier Implementation Using VB.NET

On the ASP.NET tier, we have a listener class containing a callback method to handle the notification when the cache item gets invalidated.

The callback method RemovedCallback is registered by using a delegate function. The callback method onRemove declaration must have the same signature as the CacheItemRemovedCallback delegate declaration.

    Dim onRemove As CacheItemRemovedCallback = Nothing

       onRemove = New CacheItemRemovedCallback(AddressOf RemovedCallback)

The definition for the listener event handler method RemovedCallback responsible for handling the notification from the database trigger is illustrated below. When the cache item gets invalidated, data is retrieved from the database by using the database method call getRecordFromdatabase(). The parameter "key" refers to the index location for the item removed from the cache. The parameter "value" refers to the data object removed from the cache. The parameter "CacheItemRemovedReason" specifies the reason causing the data item to be removed from the cache.

PublicSub RemovedCallback(ByVal key AsString, ByVal value AsObject,

                                                 ByVal reason As CacheItemRemovedReason)

        Dim Source As DataView

        Source = getRecordFromdatabase()

        Cache.Insert("employeeTable ", Source, New

              System.Web.Caching.CacheDependency("d:\download\tblemployee.txt"),

              Cache.NoAbsoluteExpiration, Cache.NoSlidingExpiration,

              CacheItemPriority.Normal, onRemove)

EndSub

The method getRecordFromdatabase() is responsible for querying the database table Employee and it returns a DataView object reference. It makes use of a stored procedure called getEmployee to abstract the SQL for retrieving the data from the Employee table. The method expects a parameter called p_empid representing the primary key for the Employee table.

PublicFunction getRecordFromdatabase (ByVal p_empid As Int32) As DataView

            Dim con As OracleConnection = Nothing

            Dim cmd As OracleCommand = Nothing

            Dim ds As DataSet = Nothing

            Try

                con = getDatabaseConnection(

                              "UserId=scott;Password=tiger;Data Source=testingdb;")

                cmd = New OracleCommand("Administrator.getEmployee", con)

                cmd.CommandType = CommandType.StoredProcedure

                cmd.Parameters.Add(New OracleParameter("employeeId",

                        OracleDbType.Int64)).Value = p_empid

                Dim param AsNew OracleParameter("RC1", OracleDbType.RefCursor)

                cmd.Parameters.Add(param).Direction = ParameterDirection.Output

                Dim myCommand AsNew OracleDataAdapter(cmd)

                ds = New DataSet

                myCommand.Fill(ds)

                Dim table As DataTable = ds.Tables(0)

                Dim index As Int32 = table.Rows.Count

                Return ds.Tables(0).DefaultView

            Catch ex As Exception

                ThrowNew Exception("Exception in Database Tier Method

                                getRecordFromdatabase () " + ex.Message, ex)

            Finally

                Try

                    cmd.Dispose()

                Catch ex As Exception

                Finally

                    cmd = Nothing

                EndTry

                Try

                    con.Close()

                Catch ex As Exception

                Finally

                    con = Nothing

                EndTry

            EndTry

        EndFunction

The function getDatabaseConnection accepts a connectionstring as an argument and returns an OracleConnection object reference.

PublicFunction getDatabaseConnection(ByVal strconnection as string) As

                    OracleConnection

            Dim con As Oracle.DataAccess.Client.OracleConnection = Nothing

            Try

                con = New Oracle.DataAccess.Client.OracleConnection

                con.ConnectionString = strconnection

                con.Open()

                Return con

            Catch ex As Exception

                    ThrowNew Exception("Exception in Database Tier Method

                                   getOracleConnection() " + ex.Message, ex)

            EndTry

 EndFunction

Oracle Database Tier Implementation

The Trigger body defined for DML events on the Employee Table is shown below. This trigger simply invokes a PL/SQL wrapper function for updating an operating system file called tblemployee.txt. Copies of this file are updated on two different machines called machine1 and machine2 that are running different instances of the same Web application to enable load balancing. Here administrator refers to the owner of the schema objects in the Oracle database.

begin

   administrator.plfile('machine1\\download\\ tblemployee.txt');

   administrator.plfile('machine2\\download\\ tblemployee.txt');

end;

For updating the cache dependency file, we will need to write a C function or a Java stored procedure. In our example, we chose a Java stored procedure since Oracle database server has a built-in JVM, making it easy to write Java stored procedures. Adequate memory must be allocated for the Java Pool in the System global area (SGA) of the Oracle instance. The static method updateFile accepts an absolute pathname as a parameter and creates the cache dependency file in the appropriate directory. If the file already exists, it is deleted and created again.

import java.io.*;

public class UpdFile {

  public static void updateFile(String filename) {

    try {

    File f = new File(filename);

    f.delete();

     f.createNewFile();

   }

   catch (IOException e)

   {

            // log exception

    }

  }

};

The pl/sql wrapper implementation is shown below. The wrapper function accepts the filename as a parameter and invokes the method updateFile in the Java stored procedure.

(p_filename  IN  VARCHAR2)

AS LANGUAGE JAVA

NAME 'UpdFile.updateFile (java.lang.String)';

Database Caching in a Web Farm Deployment

As illustrated in the example we have discussed, Web Servers machine1 and machine2 constitute the Web farm to provide load balancing for our Web application. Each machine runs an instance of the same Web application. In this scenario, each instance of the Web application can have its own copy of the cached data stored in its Cache object. When the employee table changes, the corresponding database trigger updates the file tblemployee.txt on both of these machines. Each instance of the Web application specifies a cache dependency on the local file tblemployee.txt, and the cache for both the instances in the Web Farm gets updated correctly, enabling the data cache on both the instances to remain in sync with the database table Employee.

Conclusion

Data Caching can be an effective technique for optimizing ASP.NET applications using the Oracle database. Although ASP.NET does not allow database dependency to be specified for the cache, Oracle triggers in conjunction with Java stored procedures can be used to extend the power of the ASP.NET cache to enable Oracle database caching. This technique can also be applied to Web Farm deployments.

Narayan Veeramani

APIs (Application Programming Interface) are application-to-application programming interfaces that support harvesting information on the web using the known web standards. These APIs are provided by the entities who wish to expose parts of their resources that a third party can use. The APIs run transparent to the user and exposes just what they want to expose, with some providing access to material for public consumption with others giving access to resources based on authentication. In a sense they may be called a basic form of SAAS.

Amazon.com, Google etc have exposed their APIs for some time. Twitter and New York Times have also exposed their API's which can be used to do some digging into the information contained in them, a kind of web mining. Many others such as Netflix have provided their own APIs described on their web sites.

What is Twitter API?

Twitter API is provided by the Social Networking and Micro-blogging service. Twitter API adheres to the web standards and one can talk to Twitter using HTTP. You can just about access anything on the Twitter web site. One example of creating a Microsoft SQL Server Report using Twitter API is available here – Tweets with Reporting Services, wherein the response from the Twitter API was in XML format. JSON (JavaScript Object Notation) is another format in which data is returned when an API call is made. In this article we will be looking at API call that returns a JSON response.

Twitter exposes a large number methods through their API's such as API's for Search, Timeline, Status, User, Direct Message, Friendship and many more. As previously mentioned the responses will be in XML or JSON. Also while some APIs may take parameters others may not.

The Twitter API used in this tutorial

We will be looking at trends in Twitter API exposed by the url, http://search.twiiter.com/trends.format. We will be using the GET method and we will expect a JSON response. Since the volume of traffic may overwhelm, the calls that you can make to this in an hour are limited (also known as rate limiting) but not critical for the demo in this tutorial.

Here is a typical call to the trends method on the Twitter API. Herein we will search for trends on the Twitter site and expect a response in JSON, if we use json instead of Format in the next URL address.

Instead of:

http://search.twitter.com/trends.Format

type-in, the following for URL address,

http://search.twitter.com/trends.json

When you plug the above in a web Brower you would get a response trends.json which you may save to your hard drive or, use it in any way you like. The next quoted text is what you get in response (note that this is what I got on Saturday 31, 2009 and what you get will be different), the content of the file trends.json you saved to your computer. Note that presently you get about top ten trends from this API call.

{"as_of":"Sat, 31 Oct 2009 20:44:46 +0000","trends":[{"name":"Happy Halloween",
"url":"http://search.twitter.com/search?q="Happy+Halloween"+OR+"Feliz+
Halloween""},{"name":"#nxzerosetechaves","url":"http://search.twitter.com/
search?q=#nxzerosetechaves"},{"name":"Danyl","url":"http://search.twitter.com/
search?q=Danyl"},{"name":"#HappyHalloween","url":"http://search.twitter.com/
search?q=#HappyHalloween"},{"name":"#potterday","url":"http://search.twitter.com/
search?q =#potterday"},{"name":"X Factor","url":"http://search.twitter.com/
search?q="X+ Factor""},{"name":"It's Halloween","url":"http://search.twitter.
com/search?q="It 's+Halloween"+OR+"Its+Halloween""},{"name":"Trick",
"url":"http://search.twitter.com/search?q=Trick+OR+#trick"},{"name":"Paranormal
Activity","url":"http://search.twitter.com/search?q="Paranormal+Activity""},
{"name":"This Is It","url":"http://search.twitter.com/search?q="This+Is+It""}]}

First of all what you see returned is a JSON object. If you are new to JSON review this article on my blog. The various elements that you see such as 'name', 'url' etc are fields in the response that are all described in the API documentation(look for Return Values). Some of the API calls can return a ton of information and you will have to know the API method so that you can correctly parse this data. Another thing you would notice is that the JSON object you get out is a nested object with many levels. You may need a JSON Parser to get a clearer picture of this nesting and I recommend using the online parser at this site. Using the above site, the JSON Object would appear as shown (only a portion is shown).

New York Times API

New York Times made available to the developers sometime in the middle of October 2008 APIs that can search New York Times for various kinds of information . Just like in Twitter there are a large number of APIs that you can use such as: Article Search; Best Sellers; Campaign Finance; Congress; and many others. Interested users can get on to this resource by signing up here requesting what APIs they would like to use. After signing up, New York Times would provide keys for the APIs that you want to access. It is important therefore, that the call should include the keys provided to you. For example, I received keys to access the following resources: Movie Reviews, Article Search, Best Sellers and Times Newswire. The key for the Movies Reviews API appears as shown here (the one shown here has been doctored and will not work).

Movie Reviews API
Key: b57378910b9fd80ecc73461547c93e8a:10:50673441

Using the New York Times API

It is a valuable resource since you can get for example with the Article Search API access to more than 2.8 million articles from 1981. Using this is quite simple, just paste the URL shown below into the address box of your browser. Note that the key shown here is fake (but of correct format).

http://api.nytimes.com/svc/search/v1/article?query=India&facets=
publication_year&api-key=6c208890a4880093c30020be8fe17a40:0:50633441

This will display in the browser the JSON object that is returned as shown. You can use the previously mentioned site to parse it for more friendly display.

{"facets" : {"publication_year" : [{"count" : 2724 , "term" : "2008"} ,
{"count" : 2345 , "term" : "2006"} , {"count" : 2311 , "term" : "2009"} ,
{"count" : 2282 , "term" : "2007"} , {"count" : 2144 , "term" : "2002"} ,
{"count" : 2111 , "term" : "2001"} , {"count" : 1988 , "term" : "2005"} ,
{"count" : 1951 , "term" : "2004"} , {"count" : 1921 , "term" : "1985"} ,
{"count" : 1798 , "term" : "2003"} , {"count" : 1761 , "term" : "1999"} ,
{"count" : 1720 , "term" : "2000"} , {"count" : 1642 , "term" : "1998"} ,
{"count" : 1442 , "term" : "1984"} , {"count" : 1382 , "term" : "1986"}]} ,
"offset" : "0" , "results" :
[{"body" : "BARSUR, India — At the edge of the Indravati River, hundreds
of miles from the nearest international border, India effectively ends.
Indian paramilitary officers point machine guns across the water.
 The dense jungles and mountains on the other side belong to Maoist rebels
dedicated to overthrowing the government. "That is their liberated" ,
"byline" : "By JIM YARDLEY" , "date" : "20091101" , "title" :
 "Maoist Rebels Widen Deadly Reach Across India" , "url" : "http://www.
nytimes.com/2009/11/01/world/asia
 /01maoist.html"} ,.........(there is more of this but abbreviated here)

Response Format

As you can see the responses to the API calls return JSON objects in general of the form shown belo

w (this one is of the form returned by the Twiiter API). What we propose to do is to use jQuery's GetJSON() method to get the JSON Objects and use Microsoft AJAX JavaScript files to display the data on the web page. Both jQuery javascript files and Microsoft ASP.NET AJAX files are both available on the Microsoft ECN (CDN). The GetJSON() method as well as the Microsoft ASP.NET AJAX templates can be easily implemented in the Visual Studio 2008 IDE. Alternatively Microsoft AJAX can also be used to retrieve data from the web sites. In this article the GetJSON() method will be used.

{"x":{"y":[{"a1":"b1", "c1":"d1"}, {"a2":"b2", "c2":"d2"}]},....
 "f":"g",....}

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">

<html xmlns="http://www.w3.org/1999/xhtml">
<head>
    <title></title>
  <script src="http://ajax.microsoft.com/ajax/jquery/jquery-1.3.2.js"
  type="text/javascript"></script>

  <style type="text/css"> .sys-template { display:none; } </style>
<script type="text/javascript"
src="http://ajax.microsoft.com/ajax/beta/0909/MicrosoftAjax.debug.js">
</script>
<script type="text/javascript"
src="http://ajax.microsoft.com/ajax/beta/0909/MicrosoftAjaxTemplates.debug.js">
</script>
 <script>
      $(document).ready(function() {
      $("#n1").css("color", "red");
      $("#n2").css("color", "green"); 

      });
   </script>
   <script type="text/javascript">

     var retval;
     var url_json = "http://localhost/AJAXEnabledWebSite2/TwitterType2.json";

         jQuery.getJSON(url_json, function(json) {

         retval = json;
         cdn();
     });

     function cdn() {

         $create(Sys.UI.DataView, {data: retval}, null, null, $get('SList'));

     }
     </script>

</head>

<body xmlns:dataview="javascript:Sys.UI.DataView"
xmlns:sys="javascript:Sys">
<h1>Twitter Stuff</h1> 

<table id="SList" class="sys-template"
border="1" style="background-color:#B0E0E6" >
<tr>      <td>{{as_of}}</td>
          <td id="n1">{{trends[0].name }}</td>
          <td id="n2">{{trends[0].url}}</td>
</tr>
</table>
</body>
</html>

{"x":{"y":["a1":"b1","a2","b2"}]},"p":"q","m":["n1":"valn1","n2":"valn2",
"n3":"valn3"],"ts":[|"v","w":"z"],"r":"s"}

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">

<html xmlns="http://www.w3.org/1999/xhtml">
<head>
    <title></title>
  <script src="http://ajax.microsoft.com/ajax/jquery/jquery-1.3.2.js"
  type="text/javascript"></script>

  <style type="text/css"> .sys-template { display:none; } </style>
<script type="text/javascript"
src="http://ajax.microsoft.com/ajax/beta/0909/MicrosoftAjax.debug.js">
</script>
<script type="text/javascript"
src="http://ajax.microsoft.com/ajax/beta/0909/MicrosoftAjaxTemplates.debug.js">
</script>
 <script>
      $(document).ready(function() {
      $("#n1").css("color", "red");
      $("#n2").css("color", "green");
        });
   </script>
   <script type="text/javascript">

     var retval;
     var url_json = "http://localhost/AJAXEnabledWebSite2/IndiaArticles.json";

         jQuery.getJSON(url_json, function(json) {

         retval = json;
         cdn();
     });

     function cdn() {

         $create(Sys.UI.DataView, {data: retval}, null, null, $get('SList'));

     }
     </script>

</head>

<body xmlns:dataview="javascript:Sys.UI.DataView"
xmlns:sys="javascript:Sys">
<h1>New York Times Articles</h1> 

<table id="SList" class="sys-template"
border="1" style="background-color:#B0E0E6" >
<tr><td>{{facets}}</td>
    <td id="n1">{{facets.publication_year[0] }}</td>
    <td>{{facets.publication_year.count}} | {{facets.publication_year.term}}</td>
    <td>{{offset}}</td>
    <td>{{results[0].body}}</td>
    <td>{{results[0].byline}}</td>
    <td>{{results[0].date}}</td>
    <td>{{results[0].title}}</td>
    <td id="l1">{{results[0].url}}</td>
</tr>
</table>
</body>
</html>

We will cover the following topics in more detail:

• What is JSF and how to install it on JBoss AS
• How to create a JSF facade for our pasture application
• How to configure JBoss Web Server

Wonder what was the first message sent through Internet? At 22:30 hours on October 29, 1969, a message was transmitted using ARPANET (the predecessor of the global Internet) on a host-to-host connection. It was meant to transmit "login". However, it transmitted just "lo" and crashed.

Developing web layout

The basic component of any Java web application is the servlet. Born in the middle of the 90s, servlets quickly gained success against their competitors, the CGI scripts. This was because of some innovative features, especially the ability to execute requests concurrently, without the overhead of creating a new process for each request. However, a few things were missing, for example, the servlet API did not address any APIs specifically for creating the client GUI. This resulted in multiple ways of creating the presentation tier, generally with tag libraries that differed from job to job and from individual developers.

The second thing that was missing in the servlet specification was a clear distinction between the presentation tier and the backend. A plethora of web frameworks tried to fill this gap; particularly the Struts framework effectively realized a clean separation of the model (application logic that interacts with a database) from the view (HTML pages presented to the client) and the controller (instance that passes information between view and model).

However, the limitation of these frameworks was that even if they realized a complete modular abstraction, they still failed as they always exposed theHttpServletRequest and HttpServletSessionobjects to their action(s). Their actions, in turn, needed to accept the interface contracts such as ActionForm, ActionMapping, and so on.

The JavaServer Faces that emerged on the stage a few years later pursued a different approach. Unlike request-driven Model–View–Controller (MVC) web frameworks, JSF chose a component-based approach that ties the user interface component to a well-defined request processing lifecycle. This greatly simplifies the development of web applications.

The JSF specification allows you to have presentation components be POJOs. This creates a cleaner separation from the servlet layer and makes it easier to do testing by not requiring the POJOs to be dependent on the servlet classes.

In the following sections, we will describe how to create a web layout for our application store using the JSF technology. For an exhaustive explanation of the JSF framework, we suggest you to surf the JSF homepage at http://java.sun.com/javaee/javaserverfaces/.

Installing JSF on JBoss AS

JBoss AS already ships with the JSF libraries, so the good news is that you don't need to download or install them in the application server. There are different implementations of the JSF libraries. Earlier JBoss releases adopted the Apache MyFaces library. JBoss AS 4.2 and 5.x ship with the Common Development and Distribution License (CDDL) implementation (now called "Project Mojarra") of the JSF 1.2 specification that is available from the java.net open source community.

Switching to another JSF implementation is anyway possible. All you have to do is package your JSF libraries with your web application and configure your web.xml to ignore the JBoss built-in implementation:

<context-param>
<param-name>org.jboss.jbossfaces.WAR_BUNDLES_JSF_
IMPL</param-name>
<param-value>true</param-value>
</context-param>

We will start by creating a new JSF project. From the File menu, select New | Other | JBoss Tools Web | JSF | JSF Web project. The JSF applet wizard will display, requesting the Project Name, the JSF Environment, and the default starting Template.

Choose AppStoreWeb as the project name, and check that the JSF Environment used is JSF 1.2. You can leave all other options to the defaults and click Finish. Eclipse will now suggest that you switch to the Web Projects view that logically assembles all JSF components. (It seems that the current release of the plugin doesn't understand your choice, so you have to manually click on the Web Projects tab.)

The key configuration file of a JSF application is faces-config.xml contained in the Configuration folder. Here you declare all navigation rules of the application and the JSF managed beans. Managed beans are simple POJOs that provide the logic for initializing and controlling JSF components, and for managing data across page requests, user sessions, or the application as a whole.

Adding JSF functionalities also requires adding some information to your web.xml file so that all requests ending with a certain suffix are intercepted by the Faces Servlet. Let's have a look at the web.xml configuration file:

<?xml version="1.0"?>
<web-app version="2.5" xmlns="http://java.sun.com/xml/ns/javaee"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://java.sun.com/xml/ns/javaee

http://java.sun.com/xml/ns/javaee/web-app_2_5.xsd">

<display-name>AppStoreWeb</display-name>
<context-param>
<param-name>javax.faces.STATE_SAVING_METHOD</param-name>
<param-value>server</param-value>
</context-param>
<context-param> [1]
<param-name>com.sun.faces.
enableRestoreView11Compatibility</param-name>
<param-value>true</param-value>
</context-param>
<listener>
<listener-class>com.sun.faces.config.
ConfigureListener</listener-class>
</listener>
<!-- Faces Servlet -->
<servlet>
<servlet-name>Faces Servlet</servlet-name>
<servlet-class>javax.faces.webapp.FacesServlet</servlet-class>
<load-on-startup>1</load-on-startup>
</servlet>
<!-- Faces Servlet Mapping -->
<servlet-mapping>
<servlet-name>Faces Servlet</servlet-name>
<url-pattern>*.jsf</url-pattern>
</servlet-mapping>
<login-config>
<auth-method>BASIC</auth-method>
</login-config>
</web-app>

The context-param pointed out here [1] is not added by default when you create a JSF application. However, it needs to be added, else you'll stumble into an annoying ViewExpiredException when your session expires (JSF 1.2).

Setting up navigation rules

In the first step, we will define the navigation rules for our AppStore. A minimalist approach would require a homepage that displays the orders, along with two additional pages for inserting new customers and new orders respectively.

Let's add the following navigation rule to the faces-config.xml:

<faces-config>
<navigation-rule>
<from-view-id>/home.jsp</from-view-id> [1]
<navigation-case>
<from-outcome>newCustomer</from-outcome> [2]
<to-view-id>/newCustomer.jsp</to-view-id>
</navigation-case>
<navigation-case>
<from-outcome>newOrder</from-outcome> [3]
<to-view-id>/newOrder.jsp</to-view-id>
</navigation-case>
</navigation-rule>
<navigation-rule>
<from-view-id></from-view-id> [4]
<navigation-case>
<from-outcome>home</from-outcome>
<to-view-id>/home.jsp</to-view-id>
</navigation-case>
</navigation-rule>
</faces-config>

In a navigation rule, you can have one from-view-id that is the (optional) starting page, and one or more landing pages that are tagged as to-view-id. The from-outcome determines the navigation flow. Think about this parameter as a Struts forward, that is, instead of embedding the landing page in the JSP/servlet, you'll simply declare a virtual path in your JSF beans.

Therefore, our starting page will be home.jsp [1] that has two possible links—the newCustomer.jsp form [2] and the newOrder.jsp form [3]. At the bottom, there is a navigation rule that is valid across all pages [4]. Every page requesting the home outcome will be redirected to the homepage of the application.

The above JSP will be created in a minute, so don't worry if Eclipse validator complains about the missing pages. This configuration can also be examined from the Diagram tab of your faces-config.xml:

The next piece of code that we will add to the confi guration is the JSF managed bean declaration. You need to declare each bean here that will be referenced by JSF pages. Add the following code snippet at the top of your faces-config.xml (just before navigation rules):

<managed-bean>
<managed-bean-name>manager</managed-bean-name> [1]
<managed-bean-class>
com.packpub.web.StoreManagerJSFBean
</managed-bean-class> [2]
<managed-bean-scope>request</managed-bean-scope> [3]
</managed-bean>

The <managed-bean-name> [1] element will be used by your JSF page to reference your beans. The <managed-bean-class> [2] is obviously the corresponding class. The managed beans can then be stored within the request, session, or application scopes, depending on the value of the <managed-bean-scope> element [3].

Adding a JSF managed bean

The StoreManagerJSFBean class follows the JavaBean patterns, providing get and set methods for its properties (to make the code more maintainable, we have skipped the getter/setter methods that simply wrap the fields of the class). We have declared the bean as request bound, so for each user of the application, JSF creates a StoreManagerJSFBean instance, which is stored within the request scope.

Add to your project a new Java class and name it com.packtpub.web.StoreManagerJSFBean:

package com.packpub.web;
// skipping imports
public class StoreManagerJSFBean {
@EJB(mappedName = "AppStoreEJB/local") [1]
private StoreManager storeManager;
private int customerId;
private int orderQuantity;
private int orderPrice;
private String customerName;
private String customerCountry;
private String orderProduct;
List<Order> listOrders;
List <SelectItem> listCustomers;
public List<SelectItem> getListCustomers() {
if (listCustomers == null) {
listCustomers= new ArrayList();
findAllCustomers();
}
return listCustomers;
}
/*
other getter/setter methods omitted for brevity
*/
public StoreManagerJSFBean() { }
public void findOrders() { [2]
listOrders = storeManager.findAllItems(this.customerId);
}
public void findAllCustomers() {
List<Customer> listCustomersEJB =
storeManager.findAllCustomers();
for(Customer customer:listCustomersEJB) {
listCustomers.add(new
SelectItem(customer.getId(),customer.getName()));
}
}
}
public void saveOrder() {
storeManager.saveOrder(customerId,this.orderPrice,
this.orderQuantity,this.orderProduct);
FacesMessage fm = new FacesMessage("Saved order for
"+this.orderQuantity+ " of "+this.orderProduct);
FacesContext.getCurrentInstance().addMessage("Message", fm);
this.orderPrice=0;
this.orderQuantity=0;
this.orderProduct=null;
}
public void insertCustomer() {
storeManager.createCustomer(this.customerCountry,
this.customerName);
FacesMessage fm = new FacesMessage(«Created Customer
«+this.customerName+ « fromf «+this.customerCountry);
FacesContext.getCurrentInstance().addMessage("Message", fm);
this.customerName=null;
this.customerCountry=null;
// Forces customer reloading
this.listCustomers=null;
}
/* Navigation rules */
public String home() { [4]
return "home";
}
public String newOrder() {
return "newOrder";
}
public String newCustomer() {
return "newCustomer";
}
}

As you can see, the StoreManagerJSFBean references the session bean we have created previously (StoreManager). Therefore, we must tell the compiler how to solve this dependency. This can be easily solved by choosing Properties on the current project, and then choosing Projects from the Java Build Path option. Add the project AppStore to your build path, as shown here:

Having fixed the compilation issues, we can now concentrate on the JSF bean. The first thing we want to capture your attention to is how the StoreManager EJB is injected [1] in the class, skipping completely the lookup/casting/exception handling part.

The findOrders() method [2] retrieves the list of orders from the StoreManager EJB. They will be displayed later in the dataTable component.

The findAllCustomers() [3] is slightly different. It recalls our entity bean's corresponding findAllCustomers() method and then populates a SelectItem object with the list of customers. SelectItem is a JSF object used to render a combobox programmatically. In our case, we will populate it with the customerId (as value) and customerName (as label).

The remaining EJB wrapper methods, saveOrder() and insertCustomer(), are quite intuitive; their job is to persist data for Orders and Customers.

The final piece of code is about navigation rules [4] that are coded as simple Java methods returning the outcome view as a string. For example, in order to return to the homepage from any other page, we will add the following button:

<h:commandButton action="#{manager.home}" value="Back" />

Setting up the view

Setting up the view JSF pages are just behind-the-scenes JSP pages that are engineered by the JSF servlet. Therefore, in order to create your views, add the following pages to your web application: home.jsp, newCustomer.jsp and newOrder.jsp. A new JSP page can be added from the Web Projects menu by right-clicking on the WebContent folder, then choosing New | File | JSP Page and naming it home.jsp.

<%@ taglib uri="http://java.sun.com/jsf/html" prefix="h"%> [1]
<%@ taglib uri="http://java.sun.com/jsf/core" prefix="f"%>
<html>
<body>
<f:view> [2]
<style type="text/css"> [3]
@import url("css/appstore.css");
</style>
<h:panelGrid columns="1" border="1" styleClass="spring"> [4]
<f:facet name="header">
<h:outputText value="Order List"/>
</f:facet>
<h:form id="listOrdersForm"> [5]
<h:outputText value="Select Customer:" /> [6]
<h:selectOneMenu id="selectCustomer"
value="#{manager.customerId}" styleClass="buttons"> [7]
<f:selectItems
value="#{manager.listCustomers}" />
</h:selectOneMenu>
<h:commandButton action="#{manager.findOrders}"
value="ListOrders" styleClass="buttons"/> [8]
<h:dataTable value="#{manager.listOrders}" var="orders"
border="1" rowClasses="row1, row2" headerClass="header"> [9]
<h:column>
<f:facet name="header">
<h:outputText value="Product" />
</f:facet>
<h:outputText value="#{orders.product}" />
</h:column>
<h:column>
<f:facet name="header">
<h:outputText value="Price" />
</f:facet>
<h:outputText value="#{orders.price}" />
</h:column>
<h:column>
<f:facet name="header">
<h:outputText value="Quantity" />
</f:facet>
<h:outputText value="#{orders.quantity}" />
</h:column>
</h:dataTable>
<h:commandButton action="#{manager.newCustomer}"
value="Insert Customer" styleClass="buttons" /> [10]
<h:commandButton action="#{manager.newOrder}"
value="Insert Order" styleClass="buttons" /> [11]
</h:form>
</h:panelGrid>
</f:view>
</body>
</html>

JSF contains two tag libraries [1] called JSF core and HTML Basic. The former provides a few general tags and some other tags that let you register validators and event listeners to UI components. The latter contains JSP tags that render HTML UI components such as buttons, text fields, checkboxes, lists, and so on. The standard prefixes of these two tag libraries are h and f, and they are declared at the beginning of home.jsp.

The view tag [2] is the container for all JavaServer Faces component tags used on a page. Stylesheets [3] are used here to decorate the UI components. The panelGrid [4] component simplifies the task of constructing a layout table, to hold form fields, labels, and buttons. In this case, it will contain the main input form.

The form element [5] manages an HTML form just the same way as standard form HTML. Rendering simple text on the page can be achieved with an outputText tag [6]. Here, you can use value-binding expressions from your JSF beans.

The selectOneMenu element [7] is used to display an HTML combobox that is bound to a bean collection. Review the findAllCustomers() method of your StoreManagerJSFBean, where the combobox is built dynamically.

The commandButton [8] is applied to render an HTML button. In our case, we have bound the button to the findOrders() method of our JSF bean.

A core JSF tag is the dataTable tag [9] that can be used to render an HTML table using a collection from the backing bean. This component is generally used to display tabular data and it offers a vast choice of built-in options for customizing its header and footer, and for paginating the table.

The last two buttons, [10] and [11], plot the route to the newCustomer and newOrder forms.

The form for inserting a new customer is as follows:

<%@ taglib uri="http://java.sun.com/jsf/html" prefix="h"%>
<%@ taglib uri="http://java.sun.com/jsf/core" prefix="f"%>
<html>
<body>
<f:view>
<style type="text/css">
@import url("css/appstore.css");
</style>
<h:form id="newCustomer">
<h:panelGrid columns="2" border="1" styleClass="spring">
<f:facet name="header">
<h:outputText value="Insert new Customer" />
</f:facet>
<h:outputText value="Name" />
<h:inputText value="#{manager.customerName}" /> [1]
<h:outputText value="Country" />
<h:inputText value="#{manager.customerCountry}" />
<h:commandButton action="#{manager.insertCustomer}" [2]
value="Insert Customer" />
<h:commandButton action="#{manager.home}" value="Back" />
</h:panelGrid>
<h:messages />
</h:form>
</f:view>
</body>
</html>

The inputText fields [1] are used to populate the individual managed bean properties. With the commandButton [2], the insertCustomer() action is recalled, thus inserting a new customer. This is the last JSP needed for our example newOrder.jsp:

<%@ taglib uri="http://java.sun.com/jsf/html" prefix="h"%>
<%@ taglib uri="http://java.sun.com/jsf/core" prefix="f"%>
<html>
<body>
<f:view>
<style type="text/css">
@import url("css/appstore.css");
</style>
<h:form id="newOrder">
<h:panelGrid columns="2" border="1" styleClass="spring">
<f:facet name="header">
<h:outputText value="Insert new Order" />
</f:facet>
<h:outputText value="Product" />
<h:inputText value="#{manager.orderProduct}" />
<h:outputText value="Quantity" />
<h:inputText value="#{manager.orderQuantity}" />
<h:outputText value="Price" />
<h:inputText value="#{manager.orderPrice}" />
<h:outputText value="Customer" />
<h:selectOneMenu id="selectCustomerforOrder"
value="#{manager.customer}">
<f:selectItems value="#{manager.listCustomers}" />
</h:selectOneMenu>
<h:commandButton action="#{manager.saveOrder}"
value="Save Order" />
<h:commandButton action="#{manager.home}" value="Back" />
</h:panelGrid>
<h:messages />
</h:form>
</f:view>
</body>
</html>

Assembling and deploying the application

So far, you have got two standalone projects, one EJB project and one web project. While you could technically deploy them separately, it is worth combining them in an Enterprise ARchive (EAR). The most obvious reason for deploying the application as an Enterprise ARchive is that the web application will be loaded by a ClassLoader in the same hierarchy as the EJB classloader. In short, you don't need to provide the EJB interfaces to the web application, as you would for a standalone application.

Packaging the application can be done entirely by Eclipse, without messing with archive files. From the menu, select New | Other | Java EE | Enterprise Application project. The next facet will request the Project name and a few details about the configuration. Your archive name will be, by default, the project name plus the extension .ear. Verify that both Target Runtime and the Configuration point correctly to the JBoss 5.0 environment.

Click Next. On the window that follows, you can select the components of your archive application, that is, the AppStore application and the AppStoreWeb component. Check the option Generate Deployment Descriptor.

Verify that META-INF/application.xml deployment descriptors contain both the modules enlisted below:

<application>
<display-name>EnterpriseStore</display-name>
<module>
<web>
<web-uri>AppStoreWeb.war</web-uri>
<context-root>AppStoreWeb</context-root>
</web>
</module>
<module>
<ejb>AppStore.jar</ejb>
</module>
</application>

Okay, now you need only a few more laps to complete the race. Let's deploy the process to JBoss by switching on the JBoss Server View. Right-click on the JBoss server and select Add and remove projects. Add the EnterpriseStore to the configured projects.

Now deploy the application in the usual way. Right-click on the EnterpriseStore and select Full Publish (at the time of writing, JBoss 5 doesn't support partial deployment of this component).

Verify from the console that the application has been deployed correctly.

Running the store

The application gateway will be home.jsf page. Point the browser to the location http://localhost:8080/AppStoreWeb/home.jsf.

Testing the application is quite simple. First add some customers and then link some orders to the customers. In the home.jsf page, check that the orders are correctly listed from the datagrid.

A last trick
Usually web applications ship with a welcome file list so that you don't have to remember anything else besides the web context. If you have already tried to add home.jsf to the welcome file list (in web.xml), you would have noticed that it doesn't work. Actually, Tomcat is a bit stubborn and requires a trick to set a JSF page as a welcome file. First, add the following to your web.xml:

<welcome-file-list>
<welcome-file>home.jsf</welcome-file>
</welcome-file-list>

Then create an empty home.jsf page in your web context root. This will trick Tomcat to detect home.jsf as the welcome file and will load home.jsp instead.

Summary

This two-part article on creating a web application is about developing and configuring web applications on JBoss AS 5.0 using the JSF cutting-edge technology. In this part of the article we have enhanced the Appstore Enterpirse application by adding a web layer to it.

In the next example, we create a new project in Visual Studio and add the reference to the project. You can skip this step if you already have a project where you would like to use the .NET Business Connector.

Open Visual Studio and create a new project as shown in the next screenshot:

When you click on OK, you will have a new C# file called Program.cs. Before we start writing any code in the file, we have to add the .NET Business Connector as a reference.

In the Solution Explorer right-click on the References node and select Add Reference.

In the form that opens select Microsoft.Dynamics.BusinessConnectorNet.dll under the Browse tab.

The file is found in the ClientBin catalog of your AX installation. The default path is:

C:Program FilesMicrosoft Dynamics Ax50ClientBin

Click on OK and note that the reference has now been added under the References node in the Solution Explorer.

Using the .NET Business Connector in .NET classes

In the next sections of this article we will look at some examples that show how we can use methods in the .NET Business Connector to call AX methods, insert data into AX tables, and read data from AX tables.

Calling a static class method in AX

You now have to go back to AX, open the AOT and find the Global class. Add the following method to the Global class:

static str AxHelloWorld()
{
    return "HelloWorld!";
}

In the Visual Studio project we open the Program.cs file again and enter the following code that will create a connection to AX through the .NET Business Connector. We then call the method we created in the Global class before it prints the result to the console:

using System;
using Microsoft.Dynamics.BusinessConnectorNet;
namespace GetAxInfo1
{
    class Program
    {
        /// <summary>
        /// This class connects to AX throught the
        /// .NET Business Connector and call the static method
        /// AxHelloWorld in the Global class in AX.
        /// The result is sent to the console (command prompt).
        /// </summary>
        /// <param name="args"></param>
        static void Main(string[] args)
        {
            Axapta ax;
            Object axObject;
            try
            {
                // Create a new Axapta object.
                ax = new Axapta();
                // Logon using the default settings
                // in the AX configuration for the .NET
                // Business Connector
                ax.Logon(null, null, null, null);
                // Call the static method and return the
                // result to the axObject variable
                axObject =
                  ax.CallStaticClassMethod("Global", "AxHelloWorld");
                // Print the result to the console
                Console.WriteLine("The message from AX is {0}",
                  axObject.ToString());
                ax.Logoff();
            }
            catch (Exception e)
            {
                Console.WriteLine(e.Message);
            }
            Console.ReadKey();
        }
    }
}

Execute the program by pressing Ctrl + F5. You should now see the following result in the console (command prompt) that opens up:

If you get a different result it might be because you haven't set up the .NET Business Connector correctly. If so, please refer to the installation guide to set it up properly. Also, check the Windows Event Viewer to see if there are any error messages that can lead you in the right direction.

Insert data into an AX table

As mentioned earlier in this article, you can use the methods in some of the marshaled classes in the .NET Business Connector to manipulate data. However, it is better to avoid this and instead have AX handle all data selection and manipulation. It would be even better to have your .NET application call a method in AX that does the job and returns the results back to the .NET application again. However, this is not always feasible, for instance, when you would like to insert records from your .NET application to an AX table. The next section will guide you through the steps needed to achieve this.

First, you should create a new project in Visual Studio as we did earlier in this article. In this example, we will call the new project "InsertAxRecord".

Then you have to add a reference to the .NET Business Connector.

In the Program.cs file (or whatever you call your file), you write something like this:

using System;
using Microsoft.Dynamics.BusinessConnectorNet;
namespace InsertAxRecord
{
    class Program
    {
        static void Main(string[] args)
        {
            Axapta ax;
            AxaptaRecord record;
            try
            {
                // Create AX object and logon to AX
                ax = new Axapta();
                ax.Logon(null, null, null, null);
                // Create a new AxaptaRecord object with
                // the name of the table as input parameter
                using (record = ax.CreateAxaptaRecord("CarTable"))
                {
                    // Remember to clear the tablebuffer if
                    // you are inserting inside a loop
                    record.Clear();
                    record.InitValue();
                    // Set the fields in the table
                    record.set_Field("CARID", "XXX1");
                    record.set_Field("MODELYEAR", 1998);
                    record.set_Field("CARBRAND", "FORD");
                    record.set_Field("MODEL", "F1");
                    record.set_Field("MILEAGE", 89378);
                    // Insert the record
                    record.Insert();
                }
                // End the AX session
                ax.Logoff();
            }
            catch (Exception e)
            {
                Console.WriteLine(e.Message);
            }
        }
    }
}

If you open the table browser and look at the contents of CarTable in AX now (find the table in the AOT and pressing Ctrl + O to open the table browser) you should see that the record has been added.

Read data from an AX table

For our next example we will repeat the procedure from the previous example, except that now we will read data from the table instead of writing to the table.

Start off by creating a new project and add the .NET Business Connector as  a reference to the solution.

Enter the following code into the Program.cs file (or whatever you call your program):

using System;
using Microsoft.Dynamics.BusinessConnectorNet;
namespace ReadAxRecord
{
    class Program
    {
        static void Main(string[] args)
        {
            Axapta ax;
            AxaptaRecord record;
            Object carId, carBrand, model, modelYear, mileage;
            try
            {
                // Create AX object and logon to AX
                ax = new Axapta();
                ax.Logon(null, null, null, null);
                // Create an AxaptaRecord object from the
                // table that will be used
                using (record = ax.CreateAxaptaRecord("CarTable"))
                {
                    // Execute the statement entered as parameter
                    record.ExecuteStmt("select * from %1
                      where %1.CarBrand like 'BMW'");
                    // Loop through the result of the statement.
                    while (record.Found)
                    {
                        // Set our local variables to be
                        // equal to the fields in the table
                        // for the current record.
                        carId = record.get_Field("CARID");
                        carBrand = record.get_Field("CARBRAND");
                        model = record.get_Field("MODEL");
                        modelYear = record.get_Field("MODELYEAR");
                        mileage = record.get_Field("MILEAGE");
                        // Write the result to the console
                        Console.WriteLine(carId + "t" +
                                          carBrand + "t" +
                                          model + "t" +
                                          modelYear + "t" +
                                          mileage);
                        // Go to the next record in the result set
                        record.Next();
                    }
                    // End the AX session
                    ax.Logoff();
                    // Make sure the console stays up
                    // until a key is pressed
                    Console.ReadKey();
                }
            }
            catch (Exception e)
            {
                Console.WriteLine(e.Message);
            }
        }
    }
}

Execute the program by pressing Ctrl + F5 and take a look at the result. It should look something like this:

Exception classes

The .NET Business Connector also consists of a number of exceptions that AX can raise. These exceptions are controlled by exception classes that will help you determine further actions if an exception occurs. In the previous example I have only used the standard .NET exception class, but if you would like to write solid code you should consider using the exceptions from the .NET Business Connector instead.

The topics covered in this article are:

• A brief description of Common Language Runtime (CLR)
• Adding .NET references to classes in AX
• Using a .NET class in X++
• Adding references to the .NET Business Connector
• Using the .NET Business Connector in .NET classes

When you are done with this article, you should be able to use .NET classes as reference classes in AX through the Common Language Runtime (CLR). The article will also guide you through the process of creating a .NET class in Visual Studio, and how to use it in AX. You will also learn how to use AX logic from external applications by using the .NET Business Connector.

All the Visual Studio examples in this article are written in C#.

Common Language Runtime

You might have done some .NET development before looking into X++ right? Maybe you're even a .NET expert? If so, you must have heard of CLR before. The CLR is a component of .NET that enables objects written in different languages to communicate with each other. CLR can be used in AX to combine functionality from .NET classes and libraries, including the ones you have yourself created in .NET. However, you cannot consume AX objects in .NET by using the CLR. Instead, you will then have to use the .NET Business Connector.

To learn more about the CLR, check out the following link: http://msdn.microsoft.com/en-us/library/ddk909ch(VS.71).aspx

One very useful feature in AX when dealing with integration between AX and .NET is the way AX implicitly converts the most common data types. For the data types listed in the next table you do not need to convert the data manually. For all other data types, you will have to convert them manually.

Enums are stored as integers in AX and are treated as integers when they are implicitly converted between .NET and AX.    

We prove this by executing the next example that shows the conversion between System.String and str. The same can be done for any of the other data types in the above table.

 static void ImplicitDataConversion(Args _args)
{
    System.String netString;
    str xppString;
    ;

    // Converting from System.String to str
    netString = "Hello AX!";
    xppString = netString;
    info(xppString);
    // Converting from str to System.String
    xppString = "Hello .NET!";
    netString = xppString;
    info(netString);
}

X++ is case insensitive, except when dealing with CLR. This means that writing System.string in the previous example will result in     a compile error, whereas writing Str instead of str will not.

The result will look like this:

Adding a reference to a .NET class in AX

To be able to use .NET classes in AX you have to make sure that the .NET assembly that you would like to use in AX exists under the References node in the AOT. If you can't find it there, you have to add it by adding a reference to the DLL file that contains the assembly in the AOT under References.

When adding a reference node in the AOT you have to make sure that the DLL exists on all client computers. If there is a client computer in which the DLL does not exist, it will result in compile errors when compiling code on that client computer.

Assembly exist in the Global Assembly Cache

Follow these steps to add a reference that exists in the Global Assembly Cache:

1. If the DLL has been added to the Global Assembly Cache, you can right-click on the Reference node in the AOT and select Add Reference.
2. In the form that opens (see next screenshot), you should be able to find the desired DLL. Add it by clicking on the Select button.
3. When you have selected the desired reference, click on the OK button. The assembly has now been added to the AOT, and can be used when writing X++ code.

        

Assembly not in Global Assembly Cache

If the file does not exist in the Global Assembly Cache follow these steps:

1. Click on the Browse button in the Add Reference form shown above and find the DLL file.
2. Click on Open. If the DLL is a valid assembly it will be added to the AOT under References.

Another option is to add the DLL to the Global Assembly Cache first and select it as described in the previous section, Assembly exist in the Global Assembly Cache.

Using a .NET class in X++

After having added a reference to the .NET assembly you want to use in AX, you can start writing the X++ code that will use the assembly.

When referencing the classes in the assembly you will need to write the whole namespace and class name. In my example I'm using an assembly that has been added to the AOT in the SYS layer. The example shows a nice feature that enables AX to send info messages to the Windows Event Log.

This can be particularly useful when you would like to use the Windows Event Log to monitor AX batch Jobs.

First, we add a new static method called writeLogEntry to the Global class:

static void writeLogEntry(Exception e, str caller, int line, str text)
{
    // Use the standard .NET class EventLog from
    // the System.Diagnostics assembly
    System.Diagnostics.EventLog     eventLog;
    // Also use a .NET enumeration from the
    // System.Diagnostics assembly
    System.Diagnostics.EventLogEntryType    entryType;
    System.Exception    clrException;
    str stack;
    Batch batch;
    str batchInfo;
    ;
    try
    {
        // Create a new object of the EventLog class
        eventLog = new System.Diagnostics.EventLog();
        eventLog.set_Source("Dynamics AX");
        // Set the enumeration value based on the Exception
        // type in AX
        switch (e)
        {
            case Exception::Info :
                entryType =
                  System.Diagnostics.EventLogEntryType::Information;
                break;
            case Exception::Warning :
                entryType =
                  System.Diagnostics.EventLogEntryType::Warning;
                break;
            case Exception::Error :
                entryType =
                  System.Diagnostics.EventLogEntryType::Error;
                break;
        }
        // If the current user is running a batch job
        // we can assume that the info message came
        // from the batch job and add additional information
        // to the event log

        while select batch
            where batch.Status == BatchStatus::Executing &&
                  batch.ExecutedBy == curuserid()
        {
            batchInfo += batch.GroupId + ': '+
              classid2name(batch.ClassNumber) + 'n';
        }
        if (batchInfo)
            eventLog.WriteEntry(strfmt("Batch info from AX: %1 nn
              The message originated from :%2 nat line %3 nn
              Message: %4", batchInfo, caller, line, text),
              entryType);
        else
            eventLog.WriteEntry(strfmt("Info from AX: nn
              The message originated from :%1 nat line %2 nn
              Message: %3", caller, line, text), entryType);
    }
    catch(Exception::CLRError)
    {
        // If not able to write the info to the eventlog
        // print an error in the print window instead.
        print "EventWriter:
          Unable to write entry to the windows eventlog";
    }
}

Then we add a line of code at the end of the add method in the Info class so that the end of the method will look like this:

       writeLogEntry(_exception, conpeek(packedAction,2) ,
          conpeek(packedAction,3), _txt);
        this.addSysInfoAction(_helpUrl, actionClassId, packedAction);
    }
    return super(_exception, (buildprefix?getprefix():'')+_txt);
}

To test the feature, simply create a new Job that prints something to the infolog:

static void TestEventLog(Args _args)
{
    ;
    info("This is a test");
}

You will now see an infolog message in AX, and if you open the Windows Event Viewer you should see the following message in the list:

Double-clicking on the event will bring up information about the origin of the info and the message that was printed to the infolog in AX.

This example could easily be extended so you can enable or disable the feature for different users and select the level of messages to be sent to the EventLog.

.NET Business Connector

If you have external applications that need to integrate directly to AX logic you can easily achieve this by using the .NET Business Connector. A typical scenario can be that you would like your .NET application to execute some code in AX and have the result sent back to the .NET application.

The .NET Business Connector requires additional licenses. Make sure that the AX installation in which you want to make use  of the .NET Business Connector has the necessary licenses before you start developing the solution.

In standard AX, the .NET Business Connector is also used by the Enterprise Portal through the Web Parts in SharePoint so that they can expose AX data and logic directly to the Web. It is also used by the standard Application Integration Framework (AIF).

The way that the .NET Business Connector works is that it offers a set of .NET managed classes that .NET applications use in order to log on to AX and execute methods in AX classes.

Here is a list of the different managed classes that can be used in .NET when you want to integrate to AX through the .NET Business Connector. The list is taken from the Dynamics AX SDK.

• How to create a discount code system
  1. How to offer different types of discounts
  2. How to take the discount into account at the shopping basket stage
• How to sell voucher codes on your store
• How to offer discounts to customers who bring us referral business

Discount codes

Discount codes are a great way to both entice new customers into a store, and also to help retain customers with special discounts. The discount code should work by allowing the customer to enter a code, which will then be verified by the store, and then a discount will be applied to the order.

The following are discount options we may wish to have available in our store:

• A fixed amount deducted from the cost of the order
• A fixed percentage deducted from the cost of the order
• The shipping cost altered, either to free or to a lower amount
• Product-based discounts (although we won't cover this one in the article)

It may also be useful to take into account the cost of the customer's basket; after all if we have a $5 discount code, we probably wouldn't want that to apply for orders of $5 or lower, and may wish to apply a minimum order amount.

Discount codes data

When storing discount codes in the framework, we need to store and account for:

• The voucher code itself, so that we can check that the customer is entering a valid code
• Whether the voucher code is active, as we may wish to prepare some voucher codes, but not have them usable until a certain time, or we may wish to discontinue a code
• A minimum value for the customer's basket, either as an incentive for the customer to purchase more or to prevent loss-making situations (for example a $10 discount on a $5 purchase!)
• The type of discount:
  1. Percentage: To indicate that the discount amount is a percentage to be removed from the cost
  2. Fixed amount deducted: To indicate that the discount amount is a fixed amount to be removed from the order total
  3. Fixed amount set to shipping: To indicate that the discount amount is to be the new value for the shipping cost
• Discount amount; that is, the amount of discount to be applied
• The number of vouchers issued, if we wish to limit the number of uses of a particular voucher code
• An expiry date, so that if we wish to have the voucher code expire, codes with a date after the stored expiry date would no longer work

Discount codes database

The following table illustrates this information as database fields within a table:

The default value for num_vouchers is -1, which we will use for vouchers that are not limited to a set number of issues.

The following code represents this data in our database:

CREATE TABLE `discount_codes` (
`ID` INT( 11 ) NOT NULL AUTO_INCREMENT ,
`vouchercode` VARCHAR( 25 ) NOT NULL ,
`active` TINYINT( 1 ) NOT NULL ,
`min_basket_cost` FLOAT NOT NULL ,
`discount_operation` ENUM( '-', '%', 's' ) NOT NULL ,
`discount_amount` FLOAT NOT NULL ,
`num_vouchers` INT( 11 ) NOT NULL DEFAULT '-1',
`expiry` TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP ,
PRIMARY KEY ( `ID` )
) ENGINE = INNODB DEFAULT CHARSET = latin1 AUTO_INCREMENT =1;

Discount codes functionality

The functionality for discount codes can be encapsulated into a single function; this function should be called when the basket is loaded and updated. (That is, if the customer changes the quantity of products in the basket, we must run this; also, if the customer adds a voucher code to their order, we must obviously call this function.)

The function needs to:

1. Check to see if the customer has entered a voucher code with their order.
2. If they have, it must look up the voucher code to see if it exists, or doesn't exist.
3. If the voucher code exists, it must check to see if the code has expired and is still able to be used (that is, that num_vouchers is greater than 0 or equal to -1).
4. Assuming this is the case, it must then check to see that the customer's basket cost is at least that of the minimum order amount in the discount codes record in the database.
5. If the voucher is able to be used, it must then determine the type of voucher, and make the relevant discount to either the basket cost, or the shipping costs.

The following code does all of this; some of the relevant sections described are highlighted within the code:

/**
  * Consider and apply voucher codes
  * Types of voucher code
  * - = FIXED AMOUNT OFF
  * % = PERCENTAGE OFF
  * s = SET NEW SHIPPING COST
  * @param voucherCode String
  * @return void
  */
  private function considerVouchers( $voucherCode )
  {
    //The voucher code value is checked to ensure it is not empty 
    // (as per point 1)
    if( $voucherCode != '' )
    {
      // we need the date, to see if the voucher has expired
      $cts = date('Y-m-d H:i:s');
      $voucher_sql = "SELECT *, if('{$cts}' > expiry, 1, 0)
                        AS expired FROM discount_codes
                      WHERE vouchercode='{$voucherCode}' LIMIT 1";
      $this->registry->getObject('db')->executeQuery( $voucher_sql );
      if( $this->registry->getObject('db')->numRows() == 0 )
      {
        $this->voucher_notice = 'Sorry, the voucher code you entered
            is invalid';
      }
      else
      {
        $voucher = $this->registry->getObject('db')->getRows();
        if( $voucher['active'] == 1 )
        {
          if( $voucher['expired'] == 1 )
          {
            $this->voucher_notice = 'Sorry, this voucher has
                expired';
            return false;
          }
          else
          {
            // check to see there are some vouchers, and customer
            // has enough in their basket (points 3 and 4)
            if( $voucher['num_vouchers'] != 0 )
            {
              if( $this->cost >= $voucher['min_basket_cost'] )
              {
                $this->discountCode = $voucherCode;
                $this->discountCodeId = $voucher['ID'];
                // If the discount operation is a percentage, then
                // the discount value is applied to the basket cost
                // to calculate that percentage. This amount is then
                // deducted from the order cost, giving a "discount
                // value"% discount from the order.
                if( $voucher['discount_operation'] == '%' )
                {
                  $this->cost = $this->
              cost - (($this->cost)/100)*$voucher['discount_amount'];
                  $this->voucher_notice = 'A '
                      . $voucher['discount_amount']
                      . '% discount has been applied to your order';
                  return true;
                  // If the discount operation is a subtraction, then
                  // the discount amount from the discount code is
                  // deducted from the order cost, and the order cost
                  // is updated to reflect this.
                }
                elseif( $voucher['discount_operation'] == '-' )
                {
                  $this->cost =
                      $this->cost - $voucher['discount_amount'];
                  $this->voucher_notice = 'A discount of £'
                      . $voucher['discount_amount']
                      . ' has been applied to your order';
                  return true;
                  // Finally, if the discount operation is set to s
                  // then, we set the shipping cost to the discount
                  // value. This could allow us to set free shipping,
                  // or just reduce shipping costs.
                }
                elseif( $voucher['discount_operation'] == 's' )
                {
                  $this->shipping_cost = $voucher['discount_amount'];
                  $this->voucher_notice = 'Your orders shipping cost
                      has been reduced to £'
                      . $voucher['discount_amount'];
                  return true;
                }
              }
              else
              {
                $this->voucher_notice = 'Sorry, your order total is
                    not enough for your order to qualify for this
                    discount code';
                return false;
              }
            }
            else
            {
              $this->voucher_notice = 'Sorry, this was a limited
                  edition voucher code, there are no more instances
                  of that code left';
              return false;
            }
          }
        }
        else
        {
          $this->voucher_notice = 'Sorry, the vocuher code you
              entered is no longer active';
          return false;
        }
      }
    }
  }

Now, we have the basis for our discount code feature. We can issue discount codes as an incentive to get new customers, or to encourage existing customers to make more purchases.

Reducing the number of codes available

One feature we added to the database structure for our discount codes was the ability to limit the number of times a voucher could be used, effectively allowing a code to be "issued" a set number of times. We need to take this into account, and reduce the number of vouchers in circulation, once one has been used.

This won't be done at this stage, but will need to be implemented at the final checkout stage when an order is updated to "paid", or the customer pays online. The following function will do this for us; it checks to see if a code is used, or if it's unlimited or has expired, and if it's not unlimited and hasn't already expired, it updates the code to decrement the number of uses remaining:

private function adjustDiscountCodeQuantities( $codeId )
{
$sql = "SELECT num_vouchers FROM discount_codes WHERE ID=" . $codeId;
$this->registry->getObject('db')->executeQuery( $sql );
if( $this->registry->getObject('db')->numRows() > 0 )
{
$codeData = $this->registry->getObject('db')->getRows();
if( $codeData['num_vouchers'] > 0 )
{
$sql = "UPDATE discount_codes SET num_vouchers=num_vouchers-1
WHERE ID=" . $codeId;
$this->registry->getObject('db')->executeQuery( $sql );
}
}
}

Purchasable voucher codes

Voucher codes work in the same way as discount codes, except that they are purchased for use by a customer, as opposed to given away for promotional reasons.

Existing functionality

The discount codes and product variation features already give us most of the functionality required for purchasable voucher codes.

Discount codes

As a voucher code has the same functionality as our discount codes, which we built earlier, we have a large portion of the functionality in place. When a voucher is purchased, a new record in the discount codes table will be made, with a num_vouchers value of 1.

Product variations

Let's say we have product variations feature built, which allows us to create a purchasable voucher code product, with variations that increase the price in increments, perhaps of $5.

Required additional functionality

We only need to add additional functionality to this if we wish to automate the process of generating a voucher code when a customer purchases a voucher code. Without additional functionality, we would simply notice a new order, manually create a new discount code, and then e-mail the customer with the code. However, automating this would save us quite a lot of time, so let's look at what would be involved in doing this:

1. First, we must wait until an order has its status updated to "paid". This would either be when a payment is made online by the customer, or when an offl ine payment is received and we, as the administrator, mark the order as "paid".
2. The order contents must be searched for anything that is a purchasable voucher code.
3. For each of these vouchers purchased, a new record must be automatically inserted into the voucher_codes table with the following values:
   • vouchercode: A randomly generated string
   • active: 1
   • min_basket_cost: The amount of the voucher purchased
   • discount_operation: (because we are subtracting an amount from the cost)
   • discount_amount: The amount of the voucher purchased
   • num_vouchers: 1
   • expiry: A year in the future would be a suitable validity period
4. These vouchers would then be sent through e-mail to the customer.

Referrals

To reward loyal customers, we may wish to offer referral discounts to them. This would work by encouraging our customers to introduce new customers, and giving them a credit based off a percentage of orders placed by customers they refer to our store. Customers referring other customers would be given a referral code, which could either be part of a link used to promote the site, or given to customers to enter somewhere on the order process.

The referral process should work like this:

1. Check for a referral code in the URL.
2. If a code is found in the URL, it should be stored in a cookie, unless a previous referral code is already being stored; in that case, the older code should be used.
3. At the checkout stage, this code should be looked up, to check if it is valid and to see the commission to be applied to the customer who passed the referral. The order number, commission value, and referring customer should be stored in a database table.
4. When the order is updated to "paid" or "paid online", the commission should be applied to the relevant customer's account.

Database changes

This requires a new database table, as well as some database alterations to work.

New table: Referrers

A referrers table is required to link customers to a unique referral code, and a commission percentage. It would require the following fields:

Changes

Customers should have a credit field, showing how much credit they have with the store based on referred customers. The orders table should also be altered to store a record of any referral code used.

Functionality

The workflow of this feature would work like this:

1. An order is placed, and a referral code is associated with it.
2. The order is marked as "paid".
3. A lookup is performed on the referrers table to find the customer and the percentage.
4. The commission value is calculated.
5. The referring customer's credit value is updated to include new commission earned.

We could extend this to record a list of transactions to a customer's credit, such as dates and amounts their account was credited by, and allow reports to be generated and sent to them. However, that could occupy several chapters itself!

Checkout process consideration

This requires an important consideration when we get to the checkout stage: we must take into account any credit stored on a customer's account. If they have credit, it should be deducted from any of their own orders, to ensure they can spend the commission they earned.

Summary

We now have a number of useful features to encourage new orders and customers to our store, as well as encouraging existing customers to promote our store through affiliate codes.

This included creating a voucher code system which supported vouchers that deducted a percentage from the order total, vouchers that deducted a fixed amount from the order total, and vouchers that altered the cost of shipping to the customer. These vouchers were able to take into account expiry dates, limited-use options, and the current cost of the customer's basket.

Taking this forward, we looked at how to extend our framework to allow customers to purchase vouchers as gifts for other customers, as well as how to extend our store to support referral bonuses and incentives for our customers.