Data & Services - PDF Service
Configure PDF generation and document processing services
Overview
The PDF Service section configures ColdFusion's PDF generation capabilities, including PDFg (PDF Generator) service integration. PDF operations include creating PDFs from HTML, merging documents, adding watermarks, form manipulation, and digital signatures.
Service Configuration
Configure how ColdFusion generates PDF documents and manages PDFg services.
PDF Service Mode
PurposeChoose between local (built-in) or remote PDF generation service
OptionsLocal: Use ColdFusion's built-in PDF engine
Remote PDFg: Connect to external PDFg server
Remote PDFg: Connect to external PDFg server
RecommendationDevelopment: Local mode for simplicity
Production: Remote PDFg for better performance and scalability
Production: Remote PDFg for better performance and scalability
ImpactRemote PDFg offloads resource-intensive PDF operations to dedicated servers
Best Practice: Run PDFg on separate servers in production to prevent PDF operations from impacting web application performance. This is especially important for high-volume PDF generation.
Remote PDFg Server Configuration
PurposeConfigure connection to external PDFg service
SettingsHost: PDFg server hostname or IP
Port: PDFg service port (default 8989)
Weight: Load balancing weight when multiple servers configured
Port: PDFg service port (default 8989)
Weight: Load balancing weight when multiple servers configured
RecommendationConfigure multiple PDFg servers for high availability and load distribution
High Availability Setup:
- Configure at least 2 PDFg servers for redundancy
- Use weight settings to distribute load evenly
- Monitor PDFg server health and availability
- Set up automatic failover between servers
PDF Service Memory Allocation
PurposeConfigure heap memory allocated to PDF generation operations
Default512 MB
RecommendationLight use: 512 MB - 1 GB
Moderate use: 1 GB - 2 GB
Heavy use: 2 GB - 4 GB
Moderate use: 1 GB - 2 GB
Heavy use: 2 GB - 4 GB
ImpactInsufficient memory causes OutOfMemoryError during complex PDF operations
Warning: Complex PDFs with many images, fonts, or pages require more memory. Monitor memory usage and increase allocation if you see OutOfMemoryError in logs.
PDF Operation Timeout
PurposeMaximum time for PDF generation operations before timeout
Default30 seconds
RecommendationSimple PDFs: 30-60 seconds
Complex reports: 120-300 seconds
Large documents: 300+ seconds
Complex reports: 120-300 seconds
Large documents: 300+ seconds
ImpactPrevents PDF operations from hanging indefinitely
Best Practice: Set timeout based on your most complex PDF operation. If generating large reports, consider asynchronous generation to avoid blocking user requests.
PDF Generation Examples
Common PDF operations using ColdFusion's PDF functionality.
Generate PDF from HTML
Convert HTML content to PDF document:
PDF from HTML
// Generate PDF from HTML content
cfdocument(format="pdf", filename="output.pdf") {
writeOutput("
<html>
<head>
<style>
body { font-family: Arial, sans-serif; }
h1 { color: #d63200; }
.content { margin: 20px; }
</style>
</head>
<body>
<h1>Sample Report</h1>
<div class='content'>
<p>This is a PDF generated from HTML.</p>
</div>
</body>
</html>
");
}<!--- Generate PDF from HTML content --->
<cfdocument format="pdf" filename="output.pdf">
<html>
<head>
<style>
body { font-family: Arial, sans-serif; }
h1 { color: #d63200; }
.content { margin: 20px; }
</style>
</head>
<body>
<h1>Sample Report</h1>
<div class="content">
<p>This is a PDF generated from HTML.</p>
</div>
</body>
</html>
</cfdocument>Merge Multiple PDFs
Combine multiple PDF files into a single document:
Merge PDFs
// Merge multiple PDF files
cfpdf(action="merge", destination="merged.pdf") {
cfpdfparam(source="document1.pdf");
cfpdfparam(source="document2.pdf");
cfpdfparam(source="document3.pdf");
}
// Alternative: Merge using array
pdfFiles = ["document1.pdf", "document2.pdf", "document3.pdf"];
cfpdf(action="merge", source=pdfFiles, destination="merged.pdf");<!--- Merge multiple PDF files --->
<cfpdf action="merge" destination="merged.pdf">
<cfpdfparam source="document1.pdf">
<cfpdfparam source="document2.pdf">
<cfpdfparam source="document3.pdf">
</cfpdf>
<!--- Alternative: Merge using array --->
<cfset pdfFiles = ["document1.pdf", "document2.pdf", "document3.pdf"]>
<cfpdf action="merge" source="#pdfFiles#" destination="merged.pdf">Add Watermark
Apply watermark to PDF documents:
PDF Watermark
// Add text watermark to PDF
cfpdf(
action="addWatermark",
source="original.pdf",
destination="watermarked.pdf",
text="CONFIDENTIAL",
rotation=45,
opacity=0.3,
foreground=true
);
// Add image watermark
cfpdf(
action="addWatermark",
source="original.pdf",
destination="watermarked.pdf",
image="logo.png",
position="0,0",
opacity=0.5
);<!--- Add text watermark to PDF --->
<cfpdf
action="addWatermark"
source="original.pdf"
destination="watermarked.pdf"
text="CONFIDENTIAL"
rotation="45"
opacity="0.3"
foreground="true">
<!--- Add image watermark --->
<cfpdf
action="addWatermark"
source="original.pdf"
destination="watermarked.pdf"
image="logo.png"
position="0,0"
opacity="0.5">Protect PDF with Password
Encrypt and password-protect PDF documents:
PDF Encryption
// Protect PDF with password
cfpdf(
action="protect",
source="document.pdf",
destination="protected.pdf",
newUserPassword="userPass123",
newOwnerPassword="ownerPass123",
permissions="AllowPrinting,AllowCopy",
encrypt="AES_128"
);
// Remove password protection
cfpdf(
action="protect",
source="protected.pdf",
destination="unprotected.pdf",
password="ownerPass123",
newUserPassword="",
newOwnerPassword=""
);<!--- Protect PDF with password --->
<cfpdf
action="protect"
source="document.pdf"
destination="protected.pdf"
newUserPassword="userPass123"
newOwnerPassword="ownerPass123"
permissions="AllowPrinting,AllowCopy"
encrypt="AES_128">
<!--- Remove password protection --->
<cfpdf
action="protect"
source="protected.pdf"
destination="unprotected.pdf"
password="ownerPass123"
newUserPassword=""
newOwnerPassword="">Best Practices
Server Separation
Run PDFg on separate servers for production environments to isolate resource-intensive PDF operations from web traffic.
Load Balancing
Use multiple PDFg instances for high-volume PDF generation with proper load distribution and failover.
Memory Allocation
Allocate sufficient memory for PDF operations based on document complexity and generation volume.
Security
Always encrypt PDFs containing sensitive information using strong passwords and AES encryption.
Asynchronous Processing
Generate large PDFs asynchronously to avoid blocking user requests and improve application responsiveness.
Monitoring
Monitor PDFg server health, memory usage, and generation times to identify performance issues early.
Common Issues & Solutions
OutOfMemoryError During PDF Generation
Symptom: PDF generation fails with OutOfMemoryError, especially for complex documents
Solutions:
- Increase PDF service memory allocation in administrator
- Increase JVM heap size for dedicated PDFg servers
- Optimize PDF content (reduce image sizes, use efficient fonts)
- Split large documents into smaller chunks
- Process PDFs in batches rather than simultaneously
PDF Generation Timeout
Symptom: PDF generation times out before completion, especially for large reports
Solutions:
- Increase PDF operation timeout setting
- Use asynchronous generation for long-running operations
- Optimize HTML/CSS for faster rendering
- Reduce document complexity (images, tables, fonts)
- Consider using dedicated PDFg servers with more resources
Connection Refused to PDFg Server
Symptom: Unable to connect to remote PDFg service, connection refused errors
Solutions:
- Verify PDFg server is running and accessible
- Check firewall rules allow connections on PDFg port (8989)
- Verify hostname/IP and port configured correctly
- Test connection from ColdFusion server to PDFg server
- Check PDFg server logs for startup errors