Note: The cfdocumentitem behavior with the default evalAtPrint value is identical to the behavior in ColdFusion MX 7, but differs from the behavior of the ColdFusion 8 release.

When the evalAtPrint attribute value is false, the default value, ColdFusion evaluates the cfdocumentitem tag body at the same time when it is processing the cfdocument tag. This is the behavior identical to CFMX7. In this case you can use CFDocument variables (TotalPageCount, CurrentPageNumber, TotalSectionpageCount and CurrentSectionpageNumber) only inside cfoutput and not in any expression because the page numbers are not known unless the cfdocument body content is evaluated and layed out.

In order to use CFDocument variables in expression inside CFDocumentItem tagbody, you should set evalAtPrint to true as shown in the following example.

<cfdocument format="pdf">
<cfdocumentitem type="header" evalAtPrint="true">
       <cfif (CFDocument.currentPageNumber % 2 eq 0)>
           <cfoutput> Page is even</cfoutput>
       <cfelse>
           <cfoutput> Page is odd</cfoutput>
       </cfif>
   </cfdocumentitem >
   Document body…
</cfdocument>

In this case, ColdFusion evaluates the cfdocumentitem tag body when it prints the header or footer, not when it evaluates the cfdocument tag body. This ensures that the cfdocument tag body is already evaluated and layed out and page number information is available when cfdocumentitem tag is being evaluated

A side effect of this is, if a variable is used inside both cfdocument and cfdocumentitem, cfdocumentitem tag will only see the final value of that variable. In the following example, cfdocumentitem will always get 11 as value of ‘I’ and hence all the headers will print ‘Chapter 11’.

<cfdocument format="pdf" >
<cfloop from=1 to=10 index="i">
   <cfdocumentsection>
   <cfdocumentitem type="header" >
       <cfoutput>Chapter #i#</cfoutput>
   </cfdocumentitem >
DocumentSection body
   </cfdocumentsection>
</cfloop>
</cfdocument>

To handle this, you can now pass the variable into the cfdocumentitem tag as a custom attribute, as shown in the following example:

<cfdocument format="pdf" >
   <strong><cfloop from=1 to=10 index="i"></strong>
       <cfdocumentsection>
           <strong><cfdocumentitem type="header" evalAtPrint="true" no = #i#>
               <cfoutput>Chapter #attributes.no#</cfoutput> </strong>
               <cfif (CFDocument.currentPageNumber % 2 eq 0)>
                   <cfoutput> Page is even</cfoutput>
               <cfelse>
                   <cfoutput> Page is odd</cfoutput>
               </cfif>
           </cfdocumentitem >
           Document Body.
       </cfdocumentsection>
   </cfloop>
</cfdocument>

Today, Andy reported a similar issue but this time it was for jpeg images. In both the cases, performance hit is huge and it does not happen with all the images.

I spent a significant amount of time debugging it today and it turns out that the reason for both the issues are same – there is something special about these images and that is colorspace. All these images actually had a different colorspace than what java imaging uses. Because of this, when we need the pixel values of image to print it on pdf (by calling BufferedImage.getRGB()), it tries to convert this colorspace to RGB colorspace and that is very very costly. That is where the entire time goes. So how do you fix it? I opened all the images in an image editor and saved it again. This time it got saved in standard RGB colorspace and the time taken to create the pdf got reduced from 110 sec to 1.5 seconds. That is huge!!! Isn’t it? But can you control all the images over the web? NO.. right? Read on.. there is more to this story.

A little bit of looking up on web pointed me to this Sun bug which is the exact same bug which we were hitting. Thankfully it got fixed in mustang i.e JDK1.6 which ColdFusion8 uses by default. But hey wait a second.. Didn’t Andy say that he is seeing it on ColdFusion 8? why do we still see this happening when it is fixed in JDK1.6? It appears that this bug was fixed only in core JDK api but not in JAI (Java advanced imaging) codecLib that ColdFusion 8 uses. So what do we do now? You can do either of these two

1. Remove clibwrapper_jiio.jar from “lib” folder.
2. Or, set this system property to the JVM. -Dcom.sun.media.imageio.disableCodecLib=true . You can set this in [cf-install_dir]/runtime/bin/jvm.config if you are using standalone coldfusion server.

You should keep in mind that codecLib libraries are native libraries which are meant to increase the java imaging performance. So disabling it might degrade the performance of CFImage somewhere. Also keep in mind that removing this jar or disabling codecLib will not result into any loss of functionality – it just means that all image operations will be pure java.

There is another related Sun’s bug which I thought might be useful to you. Image loading might get very slow if the server is running in debug mode. Your server is running in debug mode if you see something like this in your jvm.config or VM startup option.

-Xdebug -Xnoagent -Djava.compiler=NONE -Xrunjdwp:transport=dt_socket,server=y,suspend=n,address=5005

This bug got introduced in JDK1.6 and does not exist on 1.5. So make sure that you are not running the server in debug mode.

To summarise, you can do following to increase the performance of image loading in cfdocument.

1. If you are on JDK1.5, there is not much you can do. The only option is to change the colorspace of images. I will try to see if we can address this in ColdFusion code.
2. If you are on JDK1.6,
   
   • Disable codecLib as mentioned above.
   • Disable debug mode by removing the complete debug string mentioned above
3. In addition to this, you might want to use ‘localurl’ attribute for cfdocument tag. See this for more details.

<cfdocument format="pdf">
Text Outside div
<div style="width:300px;overflow:auto;">
 This is text inside the div. Will it show up?
</div><br>
</cfdocument>

In the generated pdf you will see only “Text Outside div”. Spooky.. isn’t it? The reason it happened was because of css style ‘overflow:auto’. The rendering engine used by CFDocument underneath does not handle overflow:auto and it simply ignores the content in the div. The weird part is – it considers that content for all rendering calculations including page number and page break calculation.

Something you should watch out for if you use css styles in cfdocument. A workaround for the time being is not to use overflow:auto style. So modifying the above code like this will make it work.

<cfdocument format="pdf">
Text Outside div
<div style="width:300px;">
 This is text inside the div. Will it show up?</div><br>
</cfdocument>

• PDF/Flashpaper document generated in CF8 are nearly 70% scaled down than CFMX 7. This was making document appear smaller in CF8 as compared to CF7.
• Using cfdocumentitem in a loop inside cfdocument causes the error, “routines cannot be declared more than once”.
• StackOverFlowError when a large document with table is created. A simple report with over 1500 table row causes this problem. More complex, but shorter documents have also resulted in this error. This was a pretty nasty one and it deserves a separate blog entry .

You can download the hotfix directly from here. You would need to extract the hotfix jar from the downloaded zip file and apply that jar.

1. Bookmark : You can create bookmarks for each section of the pdf using “bookmark” attribute. The bookmark created is of only one level and its name is set to the documentsection’s name. Here is a sample code for creating pdf with bookmarks.

<cfdocument format="PDF" bookmark="yes">   <cfdocumentsection name="Introduction">       <h3>Introduction</h3>       <p>The introduction goes here.</p>   </cfdocumentsection>   <cfdocumentsection name="Chapter 1">       <h3>Chapter 1: Getting Started</h3>       <p>Chapter 1 goes here.</p>   </cfdocumentsection>   <cfdocumentsection name="Chapter 2">       <h3>Chapter 2: Building Applications</h3>       <p>Chapter 2 goes here.</p>   </cfdocumentsection>   <cfdocumentsection name="Conclusion">       <h3>Conclusion</h3>       <p>The conclusion goes here.</p>   </cfdocumentsection></cfdocument>

2. Proxy Support : With ColdFusion 8, you can now provide proxy configuration to cfdocument for retrieving external content like images. This will be useful in situation where the machine hosting ColdFusion is connected to the external world via a proxy. The new attributes added for this (which are self explanatory) are listed below

• proxyHost
• proxyPort
• proxyUser
• proxyPort

3. Content from URL : Though this was added in 7.0.2, I think it makes sense to add here because it was not there in 7. Have you ever created or wanted to create a pdf from a web page? If yes, then the new attribute “src” in cfdocument and cfdocumentsection tag makes it very easy to do this. Here is an example to do this.

4. Basic Authentication : If the CFDocument body contains a resource (e.g; image or URL) that is protected with basic authentication, ColdFusion 7 can not retrieve it and it was one of the reason for getting “red-x” for images. (See my old post on this). ColdFusion 8 addresses this by adding these two attributes to cfdocument and cfdocumentsection tag.

• authuser – user name to be used for basic authentication.
• authpassword – password to be used for basic authentication.

5. User Agent : There are some cases where the web server is configured to allow requests only from a certain set of browsers (User agents to be precise) to prevent spiders and bots from overloading the server. In ColdFusion 7, when CFDocument creates a URLConnection for an image, it sends a “User-Agent” header, that looks like “User-Agent:Java/1.4.2_07″, in the HTTP request. If the web server does not recognize “Java” user-agent, it returns a status code of 404 (resource not found) and hence the images can not be displayed. ColdFusion 8 adds a new attribute “user-agent” to address this.

• user-agent : User agent to be used for making http connection. The default value will now be “ColdFusion”. If this also does not work, you can use the same string that browsers like IE or firefox use. This attribute has been added to <cfdocument> and <cfdocumentsection> tag.

6. PDF name : When a pdf generated by cfdocument is sent to the browser and you try to save it, the browser will prompt with the cfm name for the pdf which is generally not desirable. With ColdFusion 8, you can provide the appropriate name in “saveAsName” attribute of cfdocument.

• saveAsName – Name that appears in the ’saveAs’ dialog when you try to save the pdf from the browser (Generally File -> saveAs). This name will not work if you use “save” dialog of the pdf plugin.

Here is a sample code for the same.

<cfdocument format="pdf" saveAsName="mypdf"> <p>This is a PDF document.</p></cfdocument>

7. Local URLs : When CFDocument body contains a relative URL, ColdFusion will resolve the relative URL to an absolute URL and will send an HTTP request for this url. A side effect of this is – Server ends up sending HTTP request even for local URL or images that are lying on the local file system which obviously hurts the performance. In ColdFusion 8, we have added a new attribute “localURL” to cfdocument tag which if enabled, will try to resolve the relative URLs as file on the local machine.

• localURL : “true” | “false” – It should be enabled if the images used in cfdocument body are on the local machine. This would make the cfdocument engine retrieve the images directly from the file system rather then asking the server for it over http.

This attribute helps reducing the load from the server so that the same web server thread can now serve user request instead of serving local images to CFDocument. This also addresses some of the “missing image” problems which I mentioned here. Here is a sample code using this attribute.

<cfdocument format="PDF" localUrl="true"> <table>  <tr>     <td>bird</td>     <td><image src="images/bird.jpg"></td>  </tr>  <tr>     <td>Rose</td>     <td><image src="images/rose.jpg"></td>  </tr> </table></cfdocument>

8. Section Page Counts : CFDOCUMENT scope contains two new variables which give you the page counts for document section.

• TOTALSECTIONPAGECOUNT – total no of pages in the current section
• CURRENTSECTIONPAGENUMBER – Current page number in the current section.

9. Dynamic header and footer : CFDOCUMENT scope variables can now be used in expressions inside <cfdocumentitem> which makes it possible to have dynamic header and footers. You can now build logic for header/footer content based on the page number. Here is a sample code which prints section title if the page is even and prints the page no otherwise. Below is a code snippet which creates a dynamic header.

    <cfdocumentitem type="header">       <cfif (cfdocument.currentpagenumber mod 2) is 0>           <cfoutput>#sectionTitle#</cfoutput>       <cfelse>           <cfoutput>#cfdocument.currentpagenumber# of #cfdocument.TOTALPAGECOUNT#</cfoutput>        </cfif>   </cfdocumentitem>

10. We have also fixed most of the CFDocument related bugs e.g text chopping, image cropping or red-x, image scaling, “Document has no pages” etc.

1. Text getting chopped / clipped
2. Image zoom or image cropped
3. Header/Footer overwriting the text in the page body.

If you use cfdocument, it is a must have hotfix for you.

You can download the hotfix here but do not forget to read the instructions to apply this hotfix. Enjoy !

1. If you know that the URL is protected : This is the simple one. Since you know the URL is protected, add the required authorization header in the request and you are done. What if you are not making the socket connection but instead using java.net.URL or java.net.URLConnection to retrieve the content of url? You can use setRequestProperty() method of URLConnection to add any request header you want. So the code would look like

   URL url = new URL(someurlstring);
   URLConnection conn = url.openConnection();
   String encoding = new sun.misc.BASE64Encoder().encode("username:password".getBytes());
   conn.setRequestProperty ("Authorization", "Basic " + encoding);
   InputStream in = conn.getInputStream()
   ...

2. What if you dont know in advance whether the URL is protected or not? You can not arbitrarily add the authorization heder for all the URLs. The answer to this is “java.net.Authenticator”. You need to install an instance of java.net.Authenticator using setDefault() method of Authenticator. Whenever URLConnection sees that the url is protected, it will use this installed authenticator to get the username and password and set the required authorization header automatically.
   Here is how the code snippet for doing this

   Authenticator.setDefault(new MyAuthenticator());
   ....
    
   public class MyAuthenticator extends Authenticator
   {
    protected PasswordAuthentication getPasswordAuthentication()
    {
        return new PasswordAuthentication ("username", "password");
    }
   }

   This particular technique is particularly useful for people who need a workaround for retrieving password protected images in cfdocument. Here is what you need to do.

   • Use the source below to create Authenicator class

     import java.net.*;
     public class MyAuthenticator extends Authenticator
     {
         private String user;
         private String passwd;
      
         public MyAuthenticator(String user, String passwd)
         {
             this.user = user;
             this.passwd = passwd;
         }
      
         protected PasswordAuthentication getPasswordAuthentication()
         {
             return new PasswordAuthentication(user, passwd.toCharArray());
         }
     }

     Compile this and put MyAuthenticator.class in wwwroot/WEB-INF/classes.

   • Put the following code in your application.cfm or application.cfc

     <cfif not IsDefined("Application.authenticator")>
           <!--- Do initializations --->
           <cfset authenticator= createObject("java", "java.net.Authenticator")>
           <cfset myauthenticator = createObject("java", "MyAuthenticator").init("username", "password")>
           <cfset authenticator.setDefault(myauthenticator)>
           <cfset Application.authenticator=myauthenticator>
     </cfif>

     replace “username” and “password” with actual username and password.

   • give the request for the cfdocument page for which you were getting the red-x for image. The images should appear this time.

So it can either be set as jvm arguments like

or set them in the code using System.setProperty()

However since this is a system property, it gets set on the VM itself and hence it is not dynamic. In ColdFusion, since tags like ‘cfhttp’ keep them dynamic, I wanted a similar behaviour. After looking around for a while, I noticed that this capability was added in Java 1.5 aka Tiger release. (Is it only me? I keep hitting things which I feel is lacking in java API and then I find them added in 1.5 )

In Java 1.5, you can use

where proxy is an object of java.net.Proxy. Pretty neat.

However this was not a solution for me as we are still developing on JDK1.4 (need to consider all the application servers that we have to support). I stumbled upon an interesting article by Daniel Horn who faced the exact same problem. And guess what he did? Since you send an HTTP request to the proxy and then proxy sends out the actual request, he created the URL object by passing proxyHost and proxyPort as IP and port and then he gave the target url string as ‘file’ argument. This is what he did.

And it works ! Brilliant !! I wonder why this is not documented in the java API.

If the images are on local machine, it is possible to use the file url for images (or CSS,javascripts, etc). CFDocument in that case will not send requests for the images over HTTP and fetch the image directly from the file system. Here is a simple way to use the file url.

<cfdocument format="pdf">
 <cfoutput>
   Some html content
   <br>
   <img src=#localUrl("img1.gif")#><br>
   <img src=#localUrl("images/img.jpg")#>
 </cfoutput>
</cfdocument>
 
<cffunction name="localUrl" >
  <cfargument name="file" />
  <cfset var fpath = ExpandPath(file)>
  <cfset var f="">
  <cfset f = createObject("java", "java.io.File")>
  <cfset f.init(fpath)>
  <cfreturn f.toUrl().toString()>
</cffunction>

basically here I have an UDF which converts any path to local URL and then I am using that UDF in ’src’ attribute of image. This can be used to fetch images, css or any other similar contents from the local machine. You should note the <cfoutput> right under cfdocumet tag that allows the evaluation of UDF before it goes to cfdocument body.. This workaround is applicable only when the these contents are present on the same machine as ColdFusion.

This workaround has another advantage too. Normally when CFDocument body has any images, it fetches those images by sending HTTP request to the local server which is served by web threads. This has its own overhead. In a way, CFDocument uses server resource for getting something which is available locally on the server. This resource can instead be used to serve actual client http requests. Converting the image path to local urls will not go through HTTP and thus should have a better performance.

This was fixed in the hotfix 1 and is available at
http://www.adobe.com/support/coldfusion/ts/documents/aae43964/chf7010001.jar

However I would recommend you to use hotfix 2 at
http://www.adobe.com/support/coldfusion/ts/documents/aae43964/chf7010002.jar
See the details of this hotfix at http://www.adobe.com/cfusion/knowledgebase/index.cfm?id=aae43964