TechNote

ColdFusion MX 6.1: Web Service Headers with ColdFusion MX

There is currently no mechanism in ColdFusion MX 6.1 to create or process header fields in web services. This TechNote provides a patch to Apache Axis to allow users to retrieve the response headers from a web service request, as well as a hot fix to allow users to create a SOAP header in a request that has the"mustUnderstand" attribute set to be true.

There are two components to the download provided in this TechNote:

Part 1 (webservices.jar and soap-udfs.cfm) - Allows CFMX to send and receive SOAP headers. It also allows a ColdFusion component (CFC) to learn if it was invoked via SOAP or by some other mechanism such as Flash Remoting. The Web Service header functions in soap-udfs.cfm should only be used in a ColdFusion component when it is invoked via SOAP.

Part 2 (hf53566_61.jar) - Allows the mustUnderstand SOAP header attribute to be processed by CFMX. This lets CFMX set the attribute when invoking a non-CFMX web service that requires it. It also lets a ColdFusion component learn whether this attribute was set when processing a web service request header.

Note: Most customers will not need Part 2. Only if all three of the following conditions are met, should the hot fix be installed:

• Headers must be passed to an external, non-ColdFusion web service
• The web service processes headers with the "mustUnderstand" attribute set
• The web service also requires that the"mustUnderstand" attribute be set.

Note: The webservices.jar located in this download has been updated as of 3/15/04 to include the patch from Security Bulletin MPSB04-04.

SOAP Header UDF functions

Five user-defined functions are supplied in the soap-udfs.cfm file to access SOAP headers. It is necessary to installPart 1 to use these functions. For examples on how to use these functions, download examples.zip (2K)

Functions used in ColdFusion web service components (CFCs)

Parameter	Description
getRequestHeader(headerName, headerNamespace)
headerName	required	the name of the SOAP header in the request
headerNamespace	optional	the namespace for headerName
	returns	the value of the SOAP header
addResponseHeader(headerName, headerValue, headerNamespace, [mustUnderstand])
headerName	required	the name of the SOAP header for the response
headerValue	required	the value for the SOAP header
headerNamespace	optional	the namespace for headerName - default=""
mustUnderstand	optional	"true" or "false" -default="false"
	returns	void
IsViaSOAP()
	returns	"true" if the component was invoked via SOAP

Functions used to invoke (consume) web services from ColdFusion (used with cfinvoke)

Parameter	Description
addRequestHeader(webService, headerName, headerNamespace, [mustUnderstand])
webService	required	the previously created web service object
headerName	required	the name of the SOAP header in the request
headerValue	required	the value for the SOAP header
headerNamespace	optional	the namespace for headerName - default=""
mustUnderstand	optional	"true" or "false" -default="false"
	returns	void
getResponseHeader(webService, headerName, headerNamespace)
webService	required	the previously created web service object
headerName	required	the name of the SOAP header for the response
headerNamespace	optional	the namespace for headerName - default=""
	returns	the value of the SOAP header
NOTE: - The optionalmustUnderstand argument can only be used if the hot fixPart 2 is installed.

ColdFusion MX 6.1 - Server Configuration

Follow the instructions below to install the hot fix for ColdFusion MX 6.1 in the server configuration. For J2EE servers including JRun, use the instructions under the J2EE Configuration section.

Windows

1. Part 1:
2. Download the hot fix (1.3MB).
3. Stop the ColdFusion MX Application service.
4. Extract the soap-udfs.cfm file to a directory within your defined webroot.
5. Backup the existing cf_root\lib\webservices.jar file.
6. Extract the new webservices.jar from the downloaded ZIP file, into cf_root\lib\.
7. 
   Part 2:
8. Create the directory cf_root\runtime\servers\lib if it does not exist.
9. Extract hf53566_61.jar from the downloaded ZIP file, into the following directory:
   cf_root\runtime\servers\lib\
10. Restart ColdFusion.
11. Examine the ColdFusion MX Administrator System Information page and confirm that hot fix hf53566_61.jar shows in the Java Class Path list.

Unix

1. Part 1:
2. Download the hot fix (1.3MB).
3. Stop the ColdFusion MX Application service.
4. Extract the soap-udfs.cfm file to a directory within your defined webroot.
5. Backup the existing cf_root/lib/webservices.jar file.
6. Extract the new webservices.jar from the downloaded ZIP file, into cf_root/lib/.
7. 
   Part 2:
8. Create the directory cf_root/runtime/servers/lib if it does not exist.
9. Extract hf53566_61.jar from the downloaded ZIP file, into the following directory :
   cf_root/runtime/servers/lib/
10. Edit the file cf_root/runtime/bin/jvm.config:
    
    1. Locate the JVM classpath section.
    2. Add {application.home}/runtime/servers/lib as the first entry in the java.class.path list.
       
       For example:
       # JVM classpath java.class.path={application.home}/runtime/servers/lib, {application.home}/runtime/../../src, {application.home}/lib/cfusion.jar, {application.home}/runtime/lib/webservices.jar
11. Restart ColdFusion.
12. Examine the ColdFusion MX Administrator System Information page and confirm that hot fix hf53566_61.jar shows in the Java Class Path list.

ColdFusion MX 6.1 - J2EE Configuration
ColdFusion MX 6.1 - J2EE Configuration with JRun

Follow the instructions below to install the hot fix for ColdFusion MX 6.1 in the J2EE configuration with a J2EE server including JRun:

1. Part 1:
2. Download the hot fix (1.3MB).
3. Extract the soap-udfs.cfm file to a directory within your defined webroot.
4. Backup the existing cf_root/lib/webservices.jar file.
5. Extract the new webservices.jar from the downloaded ZIP file, into cf_root/lib/.
6. 
   Part 2:
7. Extract hf53566_61.jar from the downloaded ZIP file, into thecf_root/WEB-INF/lib directory.
8. Change the Context Parameter cf.class.path
   in the Deployment Descriptor (cf_root/WEB-INF/web.xml)
   for the Web Application "Macromedia ColdFusion MX" (cfusion.war)
   
   from:
   ./WEB-INF/cfusion/lib/cfusion.jar
   
   to:
   ./WEB-INF/lib/hf53566_61.jar,./WEB-INF/cfusion/lib/cfusion.jar
   
   • Note that the two paths in cf.class.path each start with a period and are separated by a comma.
   • Do not confuse ./WEB-INF/lib (which contains the hot fix jar file) with ./WEB-INF/cfusion/lib (which contains cfusion.jar).
9. Stop and restart the J2EE server for changes to take effect.
10. Examine the ColdFusion MX Administrator System Information page and confirm that hot fix hf53566_61.jar shows up in the Version section like 6,1,0 hf53566_61. Note: You will not see this jar in the Java Class Path because the hot fix jar is being loaded in the Coldfusion Class Path.
11. Repeat steps for each deployed instance of ColdFusion.

About changing the Deployment Descriptor

• Deployment Descriptor Context Parameters can be changed using the J2EE Administrator Control Panel (WebLogic and JRun) or by using the Application Assembly Tool (Websphere). If your J2EE server does not have such a tool, you must make sure that the Context Parameter change is made for all deployed instances of ColdFusion. It may be necessary to un-deploy CFMX, make the change, then re-deploy CFMX. See your J2EE documentation for other methods.
• Be sure to Persist (WebLogic) or Save (Websphere) your changes after you change the value for cf.class.path.
• You will usually need to stop and restart your J2EE server to make these changes effective.

Additional Information

---

• ColdFusion MX 6.1 confirmed issues (18795)
• ColdFusion hot fixes (all versions) (17883)

Search Support

---