FOUserAgent


1   /*
2    * Licensed to the Apache Software Foundation (ASF) under one or more
3    * contributor license agreements.  See the NOTICE file distributed with
4    * this work for additional information regarding copyright ownership.
5    * The ASF licenses this file to You under the Apache License, Version 2.0
6    * (the "License"); you may not use this file except in compliance with
7    * the License.  You may obtain a copy of the License at
8    * 
9    *      http://www.apache.org/licenses/LICENSE-2.0
10   * 
11   * Unless required by applicable law or agreed to in writing, software
12   * distributed under the License is distributed on an "AS IS" BASIS,
13   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14   * See the License for the specific language governing permissions and
15   * limitations under the License.
16   */
17  
18  /* $Id: FOUserAgent.java 433679 2006-08-22 17:49:26 +0200 (Tue, 22 Aug 2006) cbowditch $ */
19  
20  package org.apache.fop.apps;
21  
22  // Java
23  import java.io.File  ;
24  import java.util.Date  ;
25  import java.util.Map  ;
26  import javax.xml.transform.Source  ;
27  import javax.xml.transform.TransformerException  ;
28  import javax.xml.transform.URIResolver  ;
29  
30  // avalon configuration
31  import org.apache.avalon.framework.configuration.Configuration;
32  import org.apache.avalon.framework.configuration.ConfigurationException;
33  
34  // commons logging
35  import org.apache.commons.logging.Log;
36  import org.apache.commons.logging.LogFactory;
37  
38  // FOP
39  import org.apache.fop.Version;
40  import org.apache.fop.fo.FOEventHandler;
41  import org.apache.fop.pdf.PDFEncryptionParams;
42  import org.apache.fop.render.Renderer;
43  import org.apache.fop.render.RendererFactory;
44  import org.apache.fop.render.XMLHandlerRegistry;
45  import org.apache.fop.render.pdf.PDFRenderer;
46  
47  /**
48   * This is the user agent for FOP.
49   * It is the entity through which you can interact with the XSL-FO processing and is
50   * used by the processing to obtain user configurable options.
51   * <p>
52   * Renderer specific extensions (that do not produce normal areas on
53   * the output) will be done like so:
54   * <br>
55   * The extension will create an area, custom if necessary
56   * <br>
57   * this area will be added to the user agent with a key
58   * <br>
59   * the renderer will know keys for particular extensions
60   * <br>
61   * eg. bookmarks will be held in a special hierarchical area representing
62   * the title and bookmark structure
63   * <br>
64   * These areas may contain resolvable areas that will be processed
65   * with other resolvable areas
66   */
67  public class FOUserAgent {
68  
69      /** Defines the default target resolution (72dpi) for FOP */
70      public static final float DEFAULT_TARGET_RESOLUTION = 72.0f; //dpi
71  
72      private static Log log = LogFactory.getLog("FOP");
73  
74      private FopFactory factory;
75      
76      /** The base URL for all URL resolutions, especially for external-graphics */
77      private String   baseURL;
78      
79      /** A user settable URI Resolver */
80      private URIResolver   uriResolver = null;
81      
82      private float targetResolution = DEFAULT_TARGET_RESOLUTION;
83      private Map   rendererOptions = new java.util.HashMap  ();
84      private File   outputFile = null;
85      private Renderer rendererOverride = null;
86      private FOEventHandler foEventHandlerOverride = null;
87      
88      /** Producer:  Metadata element for the system/software that produces
89       * the document. (Some renderers can store this in the document.)
90       */
91      protected String   producer = "Apache FOP Version " + Version.getVersion();
92  
93      /** Creator:  Metadata element for the user that created the
94       * document. (Some renderers can store this in the document.)
95       */
96      protected String   creator = null;
97  
98      /** Creation Date:  Override of the date the document was created. 
99       * (Some renderers can store this in the document.)
100      */
101     protected Date   creationDate = null;
102     
103     /** Author of the content of the document. */
104     protected String   author = null;
105     /** Title of the document. */
106     protected String   title = null;
107     /** Set of keywords applicable to this document. */
108     protected String   keywords = null;
109     
110     /**
111      * Default constructor
112      * @see org.apache.fop.apps.FopFactory
113      * @deprecated Provided for compatibility only. Please use the methods from 
114      *             FopFactory to construct FOUserAgent instances!
115      */
116     public FOUserAgent() {
117         this(FopFactory.newInstance());
118     }
119     
120     /**
121      * Main constructor. <b>This constructor should not be called directly. Please use the 
122      * methods from FopFactory to construct FOUserAgent instances!</b>
123      * @param factory the factory that provides environment-level information
124      * @see org.apache.fop.apps.FopFactory
125      */
126     public FOUserAgent(FopFactory factory) {
127         if (factory == null) {
128             throw new NullPointerException  ("The factory parameter must not be null");
129         }
130         this.factory = factory;
131         if (factory.getUserConfig() != null) {
132             configure(factory.getUserConfig());
133         }
134     }
135     
136     /** @return the associated FopFactory instance */
137     public FopFactory getFactory() {
138         return this.factory;
139     }
140     
141     // ---------------------------------------------- rendering-run dependent stuff
142     
143     /**
144      * Sets an explicit renderer to use which overrides the one defined by the 
145      * render type setting.  
146      * @param renderer the Renderer instance to use
147      */
148     public void setRendererOverride(Renderer renderer) {
149         this.rendererOverride = renderer;
150     }
151 
152     /**
153      * Returns the overriding Renderer instance, if any.
154      * @return the overriding Renderer or null
155      */
156     public Renderer getRendererOverride() {
157         return rendererOverride;
158     }
159 
160     /**
161      * Sets an explicit FOEventHandler instance which overrides the one
162      * defined by the render type setting.  
163      * @param handler the FOEventHandler instance
164      */
165     public void setFOEventHandlerOverride(FOEventHandler handler) {
166         this.foEventHandlerOverride = handler;
167     }
168 
169     /**
170      * Returns the overriding FOEventHandler instance, if any.
171      * @return the overriding FOEventHandler or null
172      */
173     public FOEventHandler getFOEventHandlerOverride() {
174         return this.foEventHandlerOverride;
175     }
176 
177     /**
178      * Sets the producer of the document.  
179      * @param producer source of document
180      */
181     public void setProducer(String   producer) {
182         this.producer = producer;
183     }
184 
185     /**
186      * Returns the producer of the document
187      * @return producer name
188      */
189     public String   getProducer() {
190         return producer;
191     }
192 
193     /**
194      * Sets the creator of the document.  
195      * @param creator of document
196      */
197     public void setCreator(String   creator) {
198         this.creator = creator;
199     }
200 
201     /**
202      * Returns the creator of the document
203      * @return creator name
204      */
205     public String   getCreator() {
206         return creator;
207     }
208 
209     /**
210      * Sets the creation date of the document.  
211      * @param creationDate date of document
212      */
213     public void setCreationDate(Date   creationDate) {
214         this.creationDate = creationDate;
215     }
216 
217     /**
218      * Returns the creation date of the document
219      * @return creation date of document
220      */
221     public Date   getCreationDate() {
222         return creationDate;
223     }
224 
225     /**
226      * Sets the author of the document.  
227      * @param author of document
228      */
229     public void setAuthor(String   author) {
230         this.author = author;
231     }
232 
233     /**
234      * Returns the author of the document
235      * @return author name
236      */
237     public String   getAuthor() {
238         return author;
239     }
240 
241     /**
242      * Sets the title of the document. This will override any title coming from
243      * an fo:title element.  
244      * @param title of document
245      */
246     public void setTitle(String   title) {
247         this.title = title;
248     }
249 
250     /**
251      * Returns the title of the document
252      * @return title name
253      */
254     public String   getTitle() {
255         return title;
256     }
257 
258     /**
259      * Sets the keywords for the document.  
260      * @param keywords for the document
261      */
262     public void setKeywords(String   keywords) {
263         this.keywords = keywords;
264     }
265 
266     /**
267      * Returns the keywords for the document
268      * @return the keywords
269      */
270     public String   getKeywords() {
271         return keywords;
272     }
273 
274     /**
275      * Returns the renderer options
276      * @return renderer options
277      */
278     public Map   getRendererOptions() {
279         return rendererOptions;
280     }
281 
282     /**
283      * Configures the FOUserAgent through the factory's configuration.
284      * @param cfg Avalon Configuration Object
285      * @see org.apache.avalon.framework.configuration.Configurable
286      */
287     protected void configure(Configuration cfg) {
288         setBaseURL(FopFactory.getBaseURLfromConfig(cfg, "base"));
289         if (cfg.getChild("target-resolution", false) != null) {
290             this.targetResolution 
291                 = cfg.getChild("target-resolution").getValueAsFloat(
292                         DEFAULT_TARGET_RESOLUTION);
293             log.info("Target resolution set to: " + targetResolution 
294                     + "dpi (px2mm=" + getTargetPixelUnitToMillimeter() + ")");
295         }
296     }
297     
298     /**
299      * Returns the configuration subtree for a specific renderer.
300      * @param mimeType MIME type of the renderer
301      * @return the requested configuration subtree, null if there's no configuration
302      */
303     public Configuration getUserRendererConfig(String   mimeType) {
304 
305         Configuration cfg = getFactory().getUserConfig();
306         if (cfg == null || mimeType == null) {
307             return null;
308         }
309 
310         Configuration userRendererConfig = null;
311 
312         Configuration[] cfgs
313             = cfg.getChild("renderers").getChildren("renderer");
314         for (int i = 0; i < cfgs.length; ++i) {
315             Configuration child = cfgs[i];
316             try {
317                 if (child.getAttribute("mime").equals(mimeType)) {
318                     userRendererConfig = child;
319                     break;
320                 }
321             } catch (ConfigurationException e) {
322                 // silently pass over configurations without mime type
323             }
324         }
325         log.debug((userRendererConfig == null ? "No u" : "U")
326                   + "ser configuration found for MIME type " + mimeType);
327         return userRendererConfig;
328     }
329 
330     /**
331      * Sets the base URL.
332      * @param baseURL base URL
333      */
334     public void setBaseURL(String   baseURL) {
335         this.baseURL = baseURL;
336     }
337 
338     /**
339      * Returns the base URL.
340      * @return the base URL
341      */
342     public String   getBaseURL() {
343         return this.baseURL;
344     }
345 
346     /**
347      * Sets the URI Resolver.
348      * @param resolver the new URI resolver
349      */
350     public void setURIResolver(URIResolver   resolver) {
351         this.uriResolver = resolver;
352     }
353 
354     /**
355      * Returns the URI Resolver.
356      * @return the URI Resolver
357      */
358     public URIResolver   getURIResolver() {
359         return this.uriResolver;
360     }
361 
362     /**
363      * Returns the parameters for PDF encryption.
364      * @return the PDF encryption parameters, null if not applicable
365      * @deprecated Use (PDFEncryptionParams)getRendererOptions().get("encryption-params") 
366      *             instead.
367      */
368     public PDFEncryptionParams getPDFEncryptionParams() {
369         return (PDFEncryptionParams)getRendererOptions().get(PDFRenderer.ENCRYPTION_PARAMS);
370     }
371 
372     /**
373      * Sets the parameters for PDF encryption.
374      * @param pdfEncryptionParams the PDF encryption parameters, null to
375      * disable PDF encryption
376      * @deprecated Use getRendererOptions().put("encryption-params", 
377      *             new PDFEncryptionParams(..)) instead or set every parameter separately: 
378      *             getRendererOptions().put("noprint", Boolean.TRUE).
379      */
380     public void setPDFEncryptionParams(PDFEncryptionParams pdfEncryptionParams) {
381         getRendererOptions().put(PDFRenderer.ENCRYPTION_PARAMS, pdfEncryptionParams);
382     }
383 
384 
385     /**
386      * Attempts to resolve the given URI.
387      * Will use the configured resolver and if not successful fall back
388      * to the default resolver.
389      * @param uri URI to access
390      * @return A {@link javax.xml.transform.Source} object, or null if the URI
391      * cannot be resolved. 
392      * @see org.apache.fop.apps.FOURIResolver
393      */
394     public Source   resolveURI(String   uri) {
395         return resolveURI(uri, getBaseURL());
396     }
397 
398     /**
399      * Attempts to resolve the given URI.
400      * Will use the configured resolver and if not successful fall back
401      * to the default resolver.
402      * @param uri URI to access
403      * @param base the base URI to resolve against
404      * @return A {@link javax.xml.transform.Source} object, or null if the URI
405      * cannot be resolved. 
406      * @see org.apache.fop.apps.FOURIResolver
407      */
408     public Source   resolveURI(String   uri, String   base) {
409         Source   source = null;
410         //RFC 2397 data URLs don't need to be resolved, just decode them.
411         boolean bypassURIResolution = uri.startsWith("data:");
412         if (!bypassURIResolution && uriResolver != null) {
413             try {
414                 source = uriResolver.resolve(uri, base);
415             } catch (TransformerException   te) {
416                 log.error("Attempt to resolve URI '" + uri + "' failed: ", te);
417             }
418         }
419         if (source == null) {
420             // URI Resolver not configured or returned null, use default resolver from the factory
421             source = getFactory().resolveURI(uri, base);
422         }
423         return source;
424     }
425 
426     /**
427      * Sets the output File.
428      * @param f the output File
429      */
430     public void setOutputFile(File   f) {
431         this.outputFile = f;
432     }
433 
434     /**
435      * Gets the output File.
436      * @return the output File
437      */
438     public File   getOutputFile() {
439         return outputFile;
440     }
441 
442     /**
443      * Returns the conversion factor from pixel units to millimeters. This
444      * depends on the desired target resolution.
445      * @return float conversion factor
446      * @see #getTargetResolution()
447      */
448     public float getTargetPixelUnitToMillimeter() {
449         return 25.4f / this.targetResolution; 
450     }
451     
452     /** @return the resolution for resolution-dependant output */
453     public float getTargetResolution() {
454         return this.targetResolution;
455     }
456 
457     /**
458      * Sets the target resolution in dpi. This value defines the target resolution of
459      * bitmap images generated by the bitmap renderers (such as the TIFF renderer) and of
460      * bitmap images generated by filter effects in Apache Batik.
461      * @param dpi resolution in dpi
462      */
463     public void setTargetResolution(int dpi) {
464         this.targetResolution = dpi;
465     }
466     
467     // ---------------------------------------------- environment-level stuff
468     //                                                (convenience access to FopFactory methods)
469 
470     /** @return the font base URL */
471     public String   getFontBaseURL() {
472         String   fontBaseURL = getFactory().getFontBaseURL(); 
473         return fontBaseURL != null ? fontBaseURL : this.baseURL;
474     }
475 
476     /**
477      * Returns the conversion factor from pixel units to millimeters. This
478      * depends on the desired source resolution.
479      * @return float conversion factor
480      * @see #getSourceResolution()
481      */
482     public float getSourcePixelUnitToMillimeter() {
483         return getFactory().getSourcePixelUnitToMillimeter(); 
484     }
485     
486     /** @return the resolution for resolution-dependant input */
487     public float getSourceResolution() {
488         return getFactory().getSourceResolution();
489     }
490 
491     /**
492      * Gets the default page-height to use as fallback,
493      * in case page-height="auto"
494      * 
495      * @return the page-height, as a String
496      * @see FopFactory#getPageHeight()
497      */
498     public String   getPageHeight() {
499         return getFactory().getPageHeight();
500     }
501     
502     /**
503      * Gets the default page-width to use as fallback,
504      * in case page-width="auto"
505      * 
506      * @return the page-width, as a String
507      * @see FopFactory#getPageWidth()
508      */
509     public String   getPageWidth() {
510         return getFactory().getPageWidth();
511     }
512     
513     /**
514      * Returns whether FOP is strictly validating input XSL
515      * @return true of strict validation turned on, false otherwise
516      * @see FopFactory#validateStrictly()
517      */
518     public boolean validateStrictly() {
519         return getFactory().validateStrictly();
520     }
521 
522     /**
523      * @return true if the indent inheritance should be broken when crossing reference area 
524      *         boundaries (for more info, see the javadoc for the relative member variable)
525      * @see FopFactory#isBreakIndentInheritanceOnReferenceAreaBoundary()
526      */
527     public boolean isBreakIndentInheritanceOnReferenceAreaBoundary() {
528         return getFactory().isBreakIndentInheritanceOnReferenceAreaBoundary();
529     }
530 
531     /**
532      * @return the RendererFactory
533      */
534     public RendererFactory getRendererFactory() {
535         return getFactory().getRendererFactory();
536     }
537 
538     /**
539      * @return the XML handler registry
540      */
541     public XMLHandlerRegistry getXMLHandlerRegistry() {
542         return getFactory().getXMLHandlerRegistry();
543     }
544 
545 }
546 
547
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags