FOUserAgent (Apache FOP Core 2.11 API)
Date: 2025-04-24

org.apache.fop.apps

## Class FOUserAgent

- java.lang.Object
- - org.apache.fop.apps.FOUserAgent

-     public class FOUserAgent
      extends Object

  This is the user agent for FOP. It is the entity through which you can interact with the XSL-FO processing and is used by the processing to obtain user configurable options.

  Renderer specific extensions (that do not produce normal areas on the output) will be done like so:
  The extension will create an area, custom if necessary
  this area will be added to the user agent with a key
  the renderer will know keys for particular extensions
  eg. bookmarks will be held in a special hierarchical area representing the title and bookmark structure
  These areas may contain resolvable areas that will be processed with other resolvable areas

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `protected String` | `author` Author of the content of the document.
    `protected Date` | `creationDate` Creation Date: Override of the date the document was created.
    `protected String` | `creator` Creator: Metadata element for the user that created the document.
    `protected String` | `keywords` Set of keywords applicable to this document.
    `protected String` | `producer` Producer: Metadata element for the system/software that produces the document.
    `protected String` | `subject` Subject of the document.
    `protected String` | `title` Title of the document.

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `String` | `getAuthor()` Returns the author of the document
    `ColorSpaceCache` | `getColorSpaceCache()`
    `ContentHandlerFactoryRegistry` | `getContentHandlerFactoryRegistry()`
    `Date` | `getCreationDate()` Returns the creation date of the document
    `String` | `getCreator()` Returns the creator of the document
    `IFDocumentHandler` | `getDocumentHandlerOverride()` Returns the overriding `IFDocumentHandler` instance, if any.
    `ElementMappingRegistry` | `getElementMappingRegistry()`
    `EventBroadcaster` | `getEventBroadcaster()` Returns the event broadcaster that control events sent inside a processing run.
    `FOEventHandler` | `getFOEventHandlerOverride()` Returns the overriding FOEventHandler instance, if any.
    `FontManager` | `getFontManager()`
    `Map<String,String>` | `getHyphenationPatternNames()`
    `InternalResourceResolver` | `getHyphenationResourceResolver()`
    `HyphenationTreeCache` | `getHyphenationTreeCache()`
    `ImageHandlerRegistry` | `getImageHandlerRegistry()`
    `org.apache.xmlgraphics.image.loader.ImageManager` | `getImageManager()`
    `org.apache.xmlgraphics.image.loader.ImageSessionContext` | `getImageSessionContext()` Returns the image session context for the image package.
    `String` | `getKeywords()` Returns the keywords for the document
    `LayoutManagerMaker` | `getLayoutManagerMakerOverride()`
    `File` | `getOutputFile()` Gets the output File.
    `String` | `getPageHeight()` Gets the default page-height to use as fallback, in case page-height="auto"
    `String` | `getPageWidth()` Gets the default page-width to use as fallback, in case page-width="auto"
    `org.apache.xmlgraphics.image.loader.util.SoftMapCache` | `getPDFObjectCache()`
    `String` | `getProducer()` Returns the producer of the document
    `RendererConfig` | `getRendererConfig(String mimeType, RendererConfig.RendererConfigParser configCreator)` Returns the renderer configuration object for a particular MIME type.
    `Configuration` | `getRendererConfiguration(String mimeType)` Returns a `Configuration` object for which contains renderer configuration for a given MIME type.
    `RendererFactory` | `getRendererFactory()`
    `Object` | `getRendererOption(RendererConfigOption option)` Gets the renderer options given an interface representing renderer configuration options.
    `Map` | `getRendererOptions()` Returns the renderer options
    `Renderer` | `getRendererOverride()` Returns the overriding Renderer instance, if any.
    `InternalResourceResolver` | `getResourceResolver()` Returns the resource resolver.
    `float` | `getSourcePixelUnitToMillimeter()` Returns the conversion factor from pixel units to millimeters.
    `float` | `getSourceResolution()`
    `StructureTreeEventHandler` | `getStructureTreeEventHandler()` Returns the document's structure tree event handler, for use by accessible output formats.
    `String` | `getSubject()` Returns the subject of the document
    `float` | `getTargetPixelUnitToMillimeter()` Returns the conversion factor from pixel units to millimeters.
    `float` | `getTargetResolution()`
    `String` | `getTitle()` Returns the title of the document
    `Configuration` | `getUserConfig()` Get the user configuration.
    `XMLHandlerRegistry` | `getXMLHandlerRegistry()`
    `boolean` | `isAccessibilityEnabled()` Check if accessibility is enabled.
    `boolean` | `isBreakIndentInheritanceOnReferenceAreaBoundary()`
    `boolean` | `isComplexScriptFeaturesEnabled()` Check whether complex script features are enabled.
    `boolean` | `isConserveMemoryPolicyEnabled()` Check whether memory-conservation is enabled.
    `boolean` | `isKeepEmptyTags()`
    `boolean` | `isLegacyFoWrapper()`
    `boolean` | `isLegacyLastPageChangeIPD()`
    `boolean` | `isLegacySkipPagePositionOnly()`
    `boolean` | `isLocatorEnabled()` Checks if the use of Locators is enabled
    `boolean` | `isNamespaceIgnored(String namespaceURI)` Indicates whether a namespace URI is on the ignored list.
    `boolean` | `isPdfUAEnabled()`
    `boolean` | `isSimpleLineBreaking()`
    `boolean` | `isSkipPagePositionOnlyAllowed()`
    `boolean` | `isStaticRegionsPerPageForAccessibility()`
    `boolean` | `isTableBorderOverpaint()`
    `Fop` | `newFop(String outputFormat)` Returns a new `Fop` instance.
    `Fop` | `newFop(String outputFormat, OutputStream stream)` Returns a new `Fop` instance.
    `StreamSource` | `resolveURI(String uri)` Attempts to resolve the given URI.
    `void` | `setAccessibility(boolean accessibility)` Activates accessibility (for output formats that support it).
    `void` | `setAuthor(String author)` Sets the author of the document.
    `void` | `setConserveMemoryPolicy(boolean conserveMemoryPolicy)` Control whether memory-conservation should be enabled
    `void` | `setCreationDate(Date creationDate)` Sets the creation date of the document.
    `void` | `setCreator(String creator)` Sets the creator of the document.
    `void` | `setDocumentHandlerOverride(IFDocumentHandler documentHandler)` Sets an explicit document handler to use which overrides the one that would be selected by default.
    `void` | `setFOEventHandlerOverride(FOEventHandler handler)` Sets an explicit FOEventHandler instance which overrides the one defined by the render type setting.
    `void` | `setKeepEmptyTags(boolean b)`
    `void` | `setKeywords(String keywords)` Sets the keywords for the document.
    `void` | `setLocatorEnabled(boolean enableLocator)` Controls the use of SAXLocators to provide location information in error messages.
    `void` | `setOutputFile(File f)` Sets the output File.
    `void` | `setPdfUAEnabled(boolean pdfUAEnabled)`
    `void` | `setProducer(String producer)` Sets the producer of the document.
    `void` | `setRendererOverride(Renderer renderer)` Sets an explicit renderer to use which overrides the one defined by the render type setting.
    `void` | `setStaticRegionsPerPageForAccessibility(boolean staticRegionsPerPageForAccessibility)`
    `void` | `setStructureTreeEventHandler(StructureTreeEventHandler structureTreeEventHandler)` Sets the document's structure tree event handler, for use by accessible output formats.
    `void` | `setSubject(String subject)` Sets the subject of the document.
    `void` | `setTargetResolution(float dpi)` Sets the target resolution in dpi.
    `void` | `setTargetResolution(int dpi)` Sets the target resolution in dpi.
    `void` | `setTitle(String title)` Sets the title of the document.
    `boolean` | `validateStrictly()` Returns whether FOP is strictly validating input XSL
    `boolean` | `validateUserConfigStrictly()` Is the user configuration to be validated?

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Field Detail

    - #### producer

          protected String producer

      Producer: Metadata element for the system/software that produces the document. (Some renderers can store this in the document.)

    - #### creator

          protected String creator

      Creator: Metadata element for the user that created the document. (Some renderers can store this in the document.)

    - #### creationDate

          protected Date creationDate

      Creation Date: Override of the date the document was created. (Some renderers can store this in the document.)

    - #### author

          protected String author

      Author of the content of the document.

    - #### title

          protected String title

      Title of the document.

    - #### subject

          protected String subject

      Subject of the document.

    - #### keywords

          protected String keywords

      Set of keywords applicable to this document.

  - ### Method Detail

    - #### newFop

          public Fop newFop(String outputFormat,
                            OutputStream stream)
                     throws FOPException

      Returns a new `Fop` instance. Use this factory method if your output type requires an output stream and you want to configure this very rendering run, i.e. if you want to set some metadata like the title and author of the document you want to render. In that case, create a new `FOUserAgent` instance using `newFOUserAgent()`.

      MIME types are used to select the output format (ex. "application/pdf" for PDF). You can use the constants defined in `MimeConstants`.

      Parameters:
        `outputFormat` - the MIME type of the output format to use (ex. "application/pdf").
        `stream` - the output stream
      Returns:
        the new Fop instance
      Throws:
        `FOPException` - when the constructor fails

    - #### newFop

          public Fop newFop(String outputFormat)
                     throws FOPException

      Returns a new `Fop` instance. Use this factory method if you want to configure this very rendering run, i.e. if you want to set some metadata like the title and author of the document you want to render. In that case, create a new `FOUserAgent` instance using `newFOUserAgent()`.

      MIME types are used to select the output format (ex. "application/pdf" for PDF). You can use the constants defined in `MimeConstants`.

      Parameters:
        `outputFormat` - the MIME type of the output format to use (ex. "application/pdf").
      Returns:
        the new Fop instance
      Throws:
        `FOPException` - when the constructor fails

    - #### getResourceResolver

          public InternalResourceResolver getResourceResolver()

      Returns the resource resolver.
      Returns:
        the resource resolver

    - #### setDocumentHandlerOverride

          public void setDocumentHandlerOverride(IFDocumentHandler documentHandler)

      Sets an explicit document handler to use which overrides the one that would be selected by default.
      Parameters:
        `documentHandler` - the document handler instance to use

    - #### getDocumentHandlerOverride

          public IFDocumentHandler getDocumentHandlerOverride()

      Returns the overriding `IFDocumentHandler` instance, if any.
      Returns:
        the overriding document handler or null

    - #### setRendererOverride

          public void setRendererOverride(Renderer renderer)

      Sets an explicit renderer to use which overrides the one defined by the render type setting.
      Parameters:
        `renderer` - the Renderer instance to use

    - #### getRendererOverride

          public Renderer getRendererOverride()

      Returns the overriding Renderer instance, if any.
      Returns:
        the overriding Renderer or null

    - #### setFOEventHandlerOverride

          public void setFOEventHandlerOverride(FOEventHandler handler)

      Sets an explicit FOEventHandler instance which overrides the one defined by the render type setting.
      Parameters:
        `handler` - the FOEventHandler instance

    - #### getFOEventHandlerOverride

          public FOEventHandler getFOEventHandlerOverride()

      Returns the overriding FOEventHandler instance, if any.
      Returns:
        the overriding FOEventHandler or null

    - #### setProducer

          public void setProducer(String producer)

      Sets the producer of the document.
      Parameters:
        `producer` - source of document

    - #### getProducer

          public String getProducer()

      Returns the producer of the document
      Returns:
        producer name

    - #### setCreator

          public void setCreator(String creator)

      Sets the creator of the document.
      Parameters:
        `creator` - of document

    - #### getCreator

          public String getCreator()

      Returns the creator of the document
      Returns:
        creator name

    - #### setCreationDate

          public void setCreationDate(Date creationDate)

      Sets the creation date of the document.
      Parameters:
        `creationDate` - date of document

    - #### getCreationDate

          public Date getCreationDate()

      Returns the creation date of the document
      Returns:
        creation date of document

    - #### setAuthor

          public void setAuthor(String author)

      Sets the author of the document.
      Parameters:
        `author` - of document

    - #### getAuthor

          public String getAuthor()

      Returns the author of the document
      Returns:
        author name

    - #### setTitle

          public void setTitle(String title)

      Sets the title of the document. This will override any title coming from an fo:title element.
      Parameters:
        `title` - of document

    - #### getTitle

          public String getTitle()

      Returns the title of the document
      Returns:
        title name

    - #### setSubject

          public void setSubject(String subject)

      Sets the subject of the document.
      Parameters:
        `subject` - of document

    - #### getSubject

          public String getSubject()

      Returns the subject of the document
      Returns:
        the subject

    - #### setKeywords

          public void setKeywords(String keywords)

      Sets the keywords for the document.
      Parameters:
        `keywords` - for the document

    - #### getKeywords

          public String getKeywords()

      Returns the keywords for the document
      Returns:
        the keywords

    - #### getRendererOptions

          public Map getRendererOptions()

      Returns the renderer options
      Returns:
        renderer options

    - #### getRendererOption

          public Object getRendererOption(RendererConfigOption option)

      Gets the renderer options given an interface representing renderer configuration options.
      Parameters:
        `option` - the renderer option
      Returns:
        the value

    - #### resolveURI

          public StreamSource resolveURI(String uri)

      Attempts to resolve the given URI. Will use the configured resolver and if not successful fall back to the default resolver.
      Parameters:
        `uri` - URI to access
      Returns:
        A `Source` object, or null if the URI cannot be resolved.

    - #### setOutputFile

          public void setOutputFile(File f)

      Sets the output File.
      Parameters:
        `f` - the output File

    - #### getOutputFile

          public File getOutputFile()

      Gets the output File.
      Returns:
        the output File

    - #### getTargetPixelUnitToMillimeter

          public float getTargetPixelUnitToMillimeter()

      Returns the conversion factor from pixel units to millimeters. This depends on the desired target resolution.
      Returns:
        float conversion factor
      See Also:
        `getTargetResolution()`

    - #### getTargetResolution

          public float getTargetResolution()

      Returns:
        the resolution for resolution-dependant output

    - #### setTargetResolution

          public void setTargetResolution(float dpi)

      Sets the target resolution in dpi. This value defines the target resolution of bitmap images generated by the bitmap renderers (such as the TIFF renderer) and of bitmap images generated by filter effects in Apache Batik.
      Parameters:
        `dpi` - resolution in dpi

    - #### setTargetResolution

          public void setTargetResolution(int dpi)

      Sets the target resolution in dpi. This value defines the target resolution of bitmap images generated by the bitmap renderers (such as the TIFF renderer) and of bitmap images generated by filter effects in Apache Batik.
      Parameters:
        `dpi` - resolution in dpi

    - #### getImageSessionContext

          public org.apache.xmlgraphics.image.loader.ImageSessionContext getImageSessionContext()

      Returns the image session context for the image package.
      Returns:
        the ImageSessionContext instance for this rendering run

    - #### getSourcePixelUnitToMillimeter

          public float getSourcePixelUnitToMillimeter()

      Returns the conversion factor from pixel units to millimeters. This depends on the desired source resolution.
      Returns:
        float conversion factor
      See Also:
        `getSourceResolution()`

    - #### getSourceResolution

          public float getSourceResolution()

      Returns:
        the resolution for resolution-dependant input

    - #### getPageHeight

          public String getPageHeight()

      Gets the default page-height to use as fallback, in case page-height="auto"
      Returns:
        the page-height, as a String
      See Also:
        `FopFactory.getPageHeight()`

    - #### getPageWidth

          public String getPageWidth()

      Gets the default page-width to use as fallback, in case page-width="auto"
      Returns:
        the page-width, as a String
      See Also:
        `FopFactory.getPageWidth()`

    - #### validateStrictly

          public boolean validateStrictly()

      Returns whether FOP is strictly validating input XSL
      Returns:
        true of strict validation turned on, false otherwise
      See Also:
        `FopFactory.validateStrictly()`

    - #### isBreakIndentInheritanceOnReferenceAreaBoundary

          public boolean isBreakIndentInheritanceOnReferenceAreaBoundary()

      Returns:
        true if the indent inheritance should be broken when crossing reference area boundaries (for more info, see the javadoc for the relative member variable)
      See Also:
        `FopFactory.isBreakIndentInheritanceOnReferenceAreaBoundary()`

    - #### getRendererFactory

          public RendererFactory getRendererFactory()

      Returns:
        the RendererFactory

    - #### getXMLHandlerRegistry

          public XMLHandlerRegistry getXMLHandlerRegistry()

      Returns:
        the XML handler registry

    - #### setLocatorEnabled

          public void setLocatorEnabled(boolean enableLocator)

      Controls the use of SAXLocators to provide location information in error messages.
      Parameters:
        `enableLocator` - `false` if SAX Locators should be disabled

    - #### isLocatorEnabled

          public boolean isLocatorEnabled()

      Checks if the use of Locators is enabled
      Returns:
        true if context information should be stored on each node in the FO tree.

    - #### getEventBroadcaster

          public EventBroadcaster getEventBroadcaster()

      Returns the event broadcaster that control events sent inside a processing run. Clients can register event listeners with the event broadcaster to listen for events that occur while a document is being processed.
      Returns:
        the event broadcaster.

    - #### isPdfUAEnabled

          public boolean isPdfUAEnabled()

    - #### setPdfUAEnabled

          public void setPdfUAEnabled(boolean pdfUAEnabled)

    - #### isConserveMemoryPolicyEnabled

          public boolean isConserveMemoryPolicyEnabled()

      Check whether memory-conservation is enabled.
      Returns:
        true if FOP is to conserve as much as possible

    - #### setConserveMemoryPolicy

          public void setConserveMemoryPolicy(boolean conserveMemoryPolicy)

      Control whether memory-conservation should be enabled
      Parameters:
        `conserveMemoryPolicy` - the cachingEnabled to set

    - #### isComplexScriptFeaturesEnabled

          public boolean isComplexScriptFeaturesEnabled()

      Check whether complex script features are enabled.
      Returns:
        true if FOP is to use complex script features

    - #### getRendererConfig

          public RendererConfig getRendererConfig(String mimeType,
                                                  RendererConfig.RendererConfigParser configCreator)
                                           throws FOPException

      Returns the renderer configuration object for a particular MIME type.
      Parameters:
        `mimeType` - the config MIME type
        `configCreator` - the parser for creating the config for the first run of parsing.
      Returns:
        the renderer configuration object
      Throws:
        `FOPException` - if an error occurs when creating the config object

    - #### getRendererConfiguration

          public Configuration getRendererConfiguration(String mimeType)

      Returns a `Configuration` object for which contains renderer configuration for a given MIME type.
      Parameters:
        `mimeType` - the renderer configuration MIME type
      Returns:
        the configuration object

    - #### setAccessibility

          public void setAccessibility(boolean accessibility)

      Activates accessibility (for output formats that support it).
      Parameters:
        `accessibility` - `true` to enable accessibility support

    - #### isAccessibilityEnabled

          public boolean isAccessibilityEnabled()

      Check if accessibility is enabled.
      Returns:
        true if accessibility is enabled

    - #### setStaticRegionsPerPageForAccessibility

          public void setStaticRegionsPerPageForAccessibility(boolean staticRegionsPerPageForAccessibility)

    - #### isStaticRegionsPerPageForAccessibility

          public boolean isStaticRegionsPerPageForAccessibility()

    - #### setStructureTreeEventHandler

          public void setStructureTreeEventHandler(StructureTreeEventHandler structureTreeEventHandler)

      Sets the document's structure tree event handler, for use by accessible output formats.
      Parameters:
        `structureTreeEventHandler` - The structure tree event handler to set

    - #### getStructureTreeEventHandler

          public StructureTreeEventHandler getStructureTreeEventHandler()

      Returns the document's structure tree event handler, for use by accessible output formats.
      Returns:
        The structure tree event handler

    - #### getLayoutManagerMakerOverride

          public LayoutManagerMaker getLayoutManagerMakerOverride()

      See Also:
        `FopFactory.getLayoutManagerMakerOverride()`

    - #### getContentHandlerFactoryRegistry

          public ContentHandlerFactoryRegistry getContentHandlerFactoryRegistry()

      See Also:
        `FopFactory.getContentHandlerFactoryRegistry()`

    - #### getImageManager

          public org.apache.xmlgraphics.image.loader.ImageManager getImageManager()

      See Also:
        `FopFactory.getImageManager()`

    - #### getElementMappingRegistry

          public ElementMappingRegistry getElementMappingRegistry()

      See Also:
        `FopFactory.getElementMappingRegistry()`

    - #### getFontManager

          public FontManager getFontManager()

      See Also:
        `FopFactory.getFontManager()`

    - #### isNamespaceIgnored

          public boolean isNamespaceIgnored(String namespaceURI)

      Indicates whether a namespace URI is on the ignored list.
      Parameters:
        `namespaceURI` - the namespace URI
      Returns:
        true if the namespace is ignored by FOP

    - #### validateUserConfigStrictly

          public boolean validateUserConfigStrictly()

      Is the user configuration to be validated?
      Returns:
        if the user configuration should be validated

    - #### getUserConfig

          public Configuration getUserConfig()

      Get the user configuration.
      Returns:
        the user configuration

    - #### getImageHandlerRegistry

          public ImageHandlerRegistry getImageHandlerRegistry()

      Returns:
        the image handler registry

    - #### getColorSpaceCache

          public ColorSpaceCache getColorSpaceCache()

      Returns:
        the color space cache

    - #### getHyphenationPatternNames

          public Map<String,String> getHyphenationPatternNames()

      See Also:
        `FopFactory.getHyphenationPatternNames()`

    - #### getHyphenationResourceResolver

          public InternalResourceResolver getHyphenationResourceResolver()

    - #### getPDFObjectCache

          public org.apache.xmlgraphics.image.loader.util.SoftMapCache getPDFObjectCache()

    - #### getHyphenationTreeCache

          public HyphenationTreeCache getHyphenationTreeCache()

    - #### setKeepEmptyTags

          public void setKeepEmptyTags(boolean b)

    - #### isKeepEmptyTags

          public boolean isKeepEmptyTags()

    - #### isTableBorderOverpaint

          public boolean isTableBorderOverpaint()

    - #### isSimpleLineBreaking

          public boolean isSimpleLineBreaking()

    - #### isSkipPagePositionOnlyAllowed

          public boolean isSkipPagePositionOnlyAllowed()

    - #### isLegacySkipPagePositionOnly

          public boolean isLegacySkipPagePositionOnly()

    - #### isLegacyLastPageChangeIPD

          public boolean isLegacyLastPageChangeIPD()

    - #### isLegacyFoWrapper

          public boolean isLegacyFoWrapper()

Copyright © 2025 Apache Software Foundation. All rights reserved.