The Largest Repository of ColdFusion Knowledge in The World for More Than 12 Years

ColdFusion on Ulitzer

Subscribe to ColdFusion on Ulitzer: eMailAlertsEmail Alerts newslettersWeekly Newsletters
Get ColdFusion on Ulitzer: homepageHomepage mobileMobile rssRSS facebookFacebook twitterTwitter linkedinLinkedIn


CFDJ Authors: AppDynamics Blog, Michael Kopp, Tad Anderson, Bob Gourley, Jayaram Krishnaswamy

Related Topics: ColdFusion on Ulitzer, XML Magazine

CFDJ: Article

ColdFusion and XML-RPC: Part 2 of 2

ColdFusion and XML-RPC: Part 2 of 2

In the first installment of this article CFDJ (Vol. 3, issue 9), I established the benefits of secure communication between two applications.

I discussed the need for standardized communication that allows two companies to share data that would in turn enhance the service offerings of their existing applications. Through the use of the cfservlet tag, I created the foundation for communication between the ColdFusion Application Server and the JRun Application Server.

In this article I demonstrate the actual connection between the CF Server and the JRun Server, display a few intricacies associated with the exchange of data between CF and JRun, show what XML-RPC is and what it looks like, and finally work with data returned from the connected system.

Before I continue I would like to establish the theme behind this work and any work that can become the basis for true Web services. Throughout this article it should be clear that even though I utilize CF and JRun as the framework for connectivity, the real focus here is the XML-RPC, which is completely independent of any application platform.

It's also important to note that when establishing a connection between disparate systems through the use of XML-RPC, or any other XML language, it's essential to define the system in a standardized way. That means that the data models used to exchange the standard data should be general enough to allow any system to work with them. In other words, don't use data structures (data exchange functions) that are specific only to the technology you use. Instead try and establish a standard that can easily be worked with by almost any application platform. In this case, XML-RPC will be the standard means for communication, and any platform that can send, receive, and process XML-RPC packets can work with this system.

Most of the work done here to create the connection and ultimately utilize the connection between CF and JRun can be performed by someone with a little knowledge of Java. In other words, it's not necessary to be an established Java champion in order to send, receive, and process XML-RPC packets to and from CF and Java. It's safe to say, however, that without a working knowledge of Java servlets, Java data structures, and the general workings of the HTTP protocol, this will seem a little difficult.

Now let's continue with the connection to JRun.

Connection Between CF and JRun
Prior to establishing a connection between CF and JRun, it's important to take a little time to discuss the framework involved here. The JRun has two basic connection points: the Java Web Server (JWS) endpoint and the Java Connector Proxy (JCP) endpoint. Although I focus entirely on the JCP endpoint, I would like to briefly discuss the difference.

The JRun Application Server comes equipped with its own Web server that can be configured to accept requests from a Web browser: the JWS. The requests to administer the JRun Application Server and to launch servlets and JSPs directly from a Web browser are handled by the JWS. The JRun Application Server is also equipped with a different connecter module that allows JRun to handle requests sent to it from another Web server: the JCP.

The JCP will handle all of the requests from the ColdFusion Application Server, but it's important to understand the difference as it can be confusing if not explained properly (see Figure 1 for clarification of the connection types).

Figure 1
Figure  1:

In Part 1 I established that the use of the cfservlet tag from a ColdFusion template allows us to send data to a Java servlet. The cfservlet tag has parameter tags that allow it to send data via two different methods: value and reference. Let's handle a simple send of data via value.

In the example in Part 1, I discussed that I wanted to check and see if an Australian suburb was matched properly with its state name. To do so I need to connect to a module in the third-party application that will handle the process for us, the "CheckSuburb" module in this case. The cfservlet tag creates the connection to the servlet named Connect. It then sends along by value the ColdFusion variable "module" (that contains the name of the module we would like to connect with) to the JCP URL. From here the JRun Application Server loads the servlet and passes in the necessary values.

Listing 1 shows what types of methods are used with the data sent via the connection from ColdFusion. In the case of our module, I use the getParameter() method that retrieves the value of the passed-in parameter, Module. In effect, I create a new Java variable named mCall, and it gets the value of "CheckSuburb". This implementation of XML-RPC for Java contains all of the necessary components to connect to any application through the use of XML-RPC.

In the example, the getParameter() method allows me to send data from ColdFusion into a Java servlet. This type of connection occurs as a normal HTTP form post. The sending page connects to the processing page and through a post method sends variables that contain data. This name/value pair option will be extremely useful for expanding the simple module call, enabling us to make specific function calls that can be dependent upon the module we are attempting to connect to.

Although the simple name/value pair data connection option is useful, there's a more useful option to this system that I'll use to send data back to the ColdFusion template.

I can send the data to the Java servlet by reference. In the demonstration I created two types of variables to send via reference. I have the "data" variable that contains the structure with keys "State" and "Suburb" and I have the two variables "result" and "result2". Although I won't change the "data" variable, I reserve the right to do so for possible future use.

To read the data from a variable that's sent via this means, I utilize the getAttribute() method. In this demonstration, I always send a structure, so this new Java variable "data" must be cast as type Hashtable. This allows the original ColdFusion data structure to remain intact and the data to be accessible within the Java servlet.

  • Quirk #1: Connecting CF and Java Through JRun
    At this point it's important to discuss one of the major differences between CFML and other application languages. ColdFusion, for reasons associated with "speed of programming," isn't case sensitive. In other words, the following holds true:
Dog=doG

Therefore, when I create the structure "data" with keys "Suburb" and "State", the ColdFusion Application Server represents the data with uppercase key names so that the "Suburb" key becomes a key named "SUBURB". ColdFusion can handle this, but most other languages can't. If our third-party application is made up of a case-sensitive language, which in this case it is, the structure won't contain the key "Suburb" that it's looking for and probably won't continue. So, for this application, I created a Java module that will parse through the structure and rename the keys appropriately (modifyKeys()).

  • Quirk #2: CF Functions for Arrays
    It's important to note that there's a general issue when attempting to send and receive an array through this type of connection. ColdFusion doesn't store data in the "0" index of an array. Instead it begins the data storage in index "1". When you transmit an array to Java with no data in the "0" index, it throws an error. Also, when you receive data from Java that is of type Array and attempt to work with the CF Functions for Arrays, they'll throw an error.
It's possible through some different data mappings to work with arrays. Basically this involves some swapping of data into and out of structures. The best solution I have is to stick with structures when communicating in this format.

JRun with Third-Party Applications
Although the connection between the ColdFusion Application Server and the JRun Server is quite proprietary, you must understand that the "data" variable I send from CF to JRun is a standard data structure. The process to get that data from CF to JRun isn't of great importance. Once the connection is made, it's easier to think of the process as almost a direct connection between CF and the third-party application in that I send data to and from in some standard format. The JRun Server becomes just a quick intermediary step necessary to package and receive data in XML-RPC format.

Specifically, the "Connect" servlet takes the data that I send, formats it in XML-RPC (the addParameter() method), and sends it on to the third-party application (the sendCall() method). With an HTTP connection open, the servlet waits for a response from the application (see Figure 2).

Figure 2
Figure  2:

In Listing 2 you can see what the XML-RPC packet looks like. The data structure is easy to read and contains all of the information needed to perform a checkSuburb method call. It's in a simple XML format and can be read by any system that is configured to accept this type of data.

Data from Third-Party Application
Here is where the connection gets really cool. After the JRun application sends the data, it waits for a response. In the meantime, the third-party application converts the data from XML-RPC into application platform-specific data and begins to work with it. In this case the structure data is fed through the checkSuburb module and a string-formatted data element is returned. The third-party application then packages the data into XML-RPC and sends the data back to the JRun Application Server.

The data returned to JRun can be in any format. I simply cast the data returned as type Object in order to maintain its original format. In this case the data type String will be converted from XML-RPC and placed into a Java object variable named "result". The value given to "result" from the third-party application will be sent back to the CF template by using the setAttribute() module. The original CF variable "result" sent to the Java servlet via reference now has the value given to the Java object variable "result". The CF variable "result" contains the data necessary to continue processing the ColdFusion request.

Error Checking and Security
Another feature of the XML-RPC connection is that it has a standardized error-reporting system. Standard errors have been created that can be used to inform either system of specific problems, such as authentication, data structure problems, or processing errors in general. The ColdFusion application can be configured to perform different tasks to handle different errors. The system can also be modified so that errors can be added and special error-handling processes can be created to encompass flexible error checking.

Security needs arise whenever the transmission of sensitive data over the Internet is discussed - especially in this case where I have potential business logic modules available to the general public. When transmitting data over the Internet, security needs can be serviced by a simple SSL connection. The described system relies heavily on the HTTP protocol, which currently has means for encryption. The XML-RPC implementations need to simply adhere to existing standards for the transmission of secure data.

Another security issue is data module access. Utilizing a username and password can restrict a module's access; however, it's a better practice to design modules to be protected against potential harmful access attempts.

New Pathways Opening Up
Once created, the XML-RPC connection is simple to use and beneficial. On the whole, the cfservlet tag can be seen as a custom tag or cfmodule, where data gets sent to the module, some processing of the data occurs, and then it's returned. The process creates a useful tool to communicate between systems with disparate technologies, which is the main focus for Web services.

Many new standards are being discussed that allow for easy communication among different technology systems. They will open up new pathways for business partnerships and revenue streams. The combined power of ColdFusion and JRun creates a complete system that allows for extensible connectivity between almost any technology. As Java and XML become industry-wide standards - and ColdFusion and Java become more and more integrated - XML-RPC solutions and similar implementations will become easier to work with.

More Stories By Ronald West

Ronald West is the director of technology for ACES Technologies, where he designs and manages large-scale ASPs for the healthcare industry. He has designed and managed Internet services for middle-sized underwriters, including intranet, extranet, and network architecture design and deployment.

Comments (0)

Share your thoughts on this story.

Add your comment
You must be signed in to add a comment. Sign-in | Register

In accordance with our Comment Policy, we encourage comments that are on topic, relevant and to-the-point. We will remove comments that include profanity, personal attacks, racial slurs, threats of violence, or other inappropriate material that violates our Terms and Conditions, and will block users who make repeated violations. We ask all readers to expect diversity of opinion and to treat one another with dignity and respect.