Made the necessary changes to remove the long-standing deprecations in the apps package as discussed.

git-svn-id: https://svn.apache.org/repos/asf/xmlgraphics/fop/trunk@628826 13f79535-47bb-0310-9956-ffa450edef68

3 files changed, 22 insertions, 116 deletions

diff --git a/src/java/org/apache/fop/apps/FOUserAgent.java b/src/java/org/apache/fop/apps/FOUserAgent.java
index 966e227fe..a7405b466 100644
--- a/src/java/org/apache/fop/apps/FOUserAgent.java
+++ b/src/java/org/apache/fop/apps/FOUserAgent.java
@@ -37,11 +37,9 @@ import org.apache.xmlgraphics.image.loader.impl.AbstractImageSessionContext;
 
 import org.apache.fop.Version;
 import org.apache.fop.fo.FOEventHandler;
-import org.apache.fop.pdf.PDFEncryptionParams;
 import org.apache.fop.render.Renderer;
 import org.apache.fop.render.RendererFactory;
 import org.apache.fop.render.XMLHandlerRegistry;
-import org.apache.fop.render.pdf.PDFRenderer;
 
 /**
  * This is the user agent for FOP.
@@ -66,7 +64,8 @@ import org.apache.fop.render.pdf.PDFRenderer;
 public class FOUserAgent {
 
     /** Defines the default target resolution (72dpi) for FOP */
-    public static final float DEFAULT_TARGET_RESOLUTION = FopFactoryConfigurator.DEFAULT_TARGET_RESOLUTION;
+    public static final float DEFAULT_TARGET_RESOLUTION
+            = FopFactoryConfigurator.DEFAULT_TARGET_RESOLUTION;
 
     private static Log log = LogFactory.getLog("FOP");
 
@@ -130,16 +129,6 @@ public class FOUserAgent {
     };
     
     /**
-     * Default constructor
-     * @see org.apache.fop.apps.FopFactory
-     * @deprecated Provided for compatibility only. Please use the methods from 
-     *             FopFactory to construct FOUserAgent instances!
-     */
-    public FOUserAgent() throws FOPException {
-        this(FopFactory.newInstance());
-    }
-    
-    /**
      * Main constructor. <b>This constructor should not be called directly. Please use the 
      * methods from FopFactory to construct FOUserAgent instances!</b>
      * @param factory the factory that provides environment-level information
@@ -342,29 +331,6 @@ public class FOUserAgent {
     }
 
     /**
-     * Returns the parameters for PDF encryption.
-     * @return the PDF encryption parameters, null if not applicable
-     * @deprecated Use (PDFEncryptionParams)getRendererOptions().get("encryption-params") 
-     *             instead.
-     */
-    public PDFEncryptionParams getPDFEncryptionParams() {
-        return (PDFEncryptionParams)getRendererOptions().get(PDFRenderer.ENCRYPTION_PARAMS);
-    }
-
-    /**
-     * Sets the parameters for PDF encryption.
-     * @param pdfEncryptionParams the PDF encryption parameters, null to
-     * disable PDF encryption
-     * @deprecated Use getRendererOptions().put("encryption-params", 
-     *             new PDFEncryptionParams(..)) instead or set every parameter separately: 
-     *             getRendererOptions().put("noprint", Boolean.TRUE).
-     */
-    public void setPDFEncryptionParams(PDFEncryptionParams pdfEncryptionParams) {
-        getRendererOptions().put(PDFRenderer.ENCRYPTION_PARAMS, pdfEncryptionParams);
-    }
-
-
-    /**
      * Attempts to resolve the given URI.
      * Will use the configured resolver and if not successful fall back
      * to the default resolver.
diff --git a/src/java/org/apache/fop/apps/Fop.java b/src/java/org/apache/fop/apps/Fop.java
index a7602a981..d1a56789f 100644
--- a/src/java/org/apache/fop/apps/Fop.java
+++ b/src/java/org/apache/fop/apps/Fop.java
@@ -22,10 +22,8 @@ package org.apache.fop.apps;
 // Java
 import java.io.OutputStream;
 
-// XML
 import org.xml.sax.helpers.DefaultHandler;
 
-// FOP
 import org.apache.fop.fo.FOTreeBuilder;
 
 /**
@@ -66,10 +64,8 @@ public class Fop {
      * @param ua FOUserAgent object
      * @param stream the output stream
      * @throws FOPException if setting up the DefaultHandler fails
-     * @deprecated End-users should use {@link FopFactory#newFop(String, FOUserAgent, OutputStream)} 
-     *             instead! This constructor will become invisible with FOP 1.0.
      */
-    public Fop(String outputFormat, FOUserAgent ua, OutputStream stream) throws FOPException {
+    Fop(String outputFormat, FOUserAgent ua, OutputStream stream) throws FOPException {
         this.outputFormat = outputFormat;
 
         foUserAgent = ua;
@@ -83,39 +79,7 @@ public class Fop {
     }
 
     /**
-     * Constructor for use with already-created FOUserAgents. It uses MIME types to select the 
-     * output format (ex. "application/pdf" for PDF).
-     * @param outputFormat the MIME type of the output format to use (ex. "application/pdf").
-     * @param ua FOUserAgent object
-     * @throws FOPException if setting up the DefaultHandler fails
-     * @deprecated End-users should use {@link FopFactory#newFop(String, FOUserAgent)} instead!
-     *             This constructor will become invisible with FOP 1.0.
-     */
-    public Fop(String outputFormat, FOUserAgent ua) throws FOPException {
-        this.outputFormat = outputFormat;
-
-        foUserAgent = ua;
-        if (foUserAgent == null) {
-            foUserAgent = FopFactory.newInstance().newFOUserAgent();
-        }
-        
-        createDefaultHandler();
-    }
-
-    /**
-     * Constructor for FOP with a default FOUserAgent. It uses MIME types to select the 
-     * output format (ex. "application/pdf" for PDF).
-     * @param outputFormat the MIME type of the output format to use (ex. "application/pdf").
-     * @deprecated End-users should use {@link FopFactory#newFop(String)} instead!
-     *             This constructor will become invisible with FOP 1.0.
-     */
-    public Fop(String outputFormat) {
-        this.outputFormat = outputFormat;
-        foUserAgent = FopFactory.newInstance().newFOUserAgent();
-    }
-
-    /**
-     * Get the FOUserAgent instance for this process
+     * Get the FOUserAgent instance associated with the rendering run represented by this instance.
      * @return the user agent
      */
     public FOUserAgent getUserAgent() {
@@ -123,17 +87,6 @@ public class Fop {
     }
 
     /**
-     * Set the OutputStream to use to output the result of the Render
-     * (if applicable)
-     * @param stream the stream to output the result of rendering to
-     * @deprecated Use one of the factory methods on {@link FopFactory} with an OutputStream
-     *             parameter instead. This method will be removed with FOP 1.0.
-     */
-    public void setOutputStream(OutputStream stream) {
-        this.stream = stream;
-    }
-
-    /**
      * Creates a DefaultHandler object used to generate the document.
      * Note this object implements the ContentHandler interface.
      * For processing with a Transformer object, this DefaultHandler object
@@ -148,8 +101,8 @@ public class Fop {
     }
 
     /**
-     * Returns the DefaultHandler object used to generate the document.
-     * Checking for null and the exception is only for the deprecated constructor.
+     * Returns the DefaultHandler object that will receive the SAX stream containing the
+     * FO document to be rendered.
      * @return the SAX DefaultHandler for handling the SAX events.
      * @throws FOPException if setting up the DefaultHandler fails
      */
@@ -178,13 +131,4 @@ public class Fop {
         }
     }
 
-    /**
-     * Get the version of FOP
-     * @return the version string
-     * @deprecated Use {@link org.apache.fop.Version#getVersion()} instead!
-     *             This method will be removed with FOP 1.0.
-     */
-    public static String getVersion() {
-        return org.apache.fop.Version.getVersion();
-    }
 }
diff --git a/src/java/org/apache/fop/apps/FopFactory.java b/src/java/org/apache/fop/apps/FopFactory.java
index de4c43626..e6ac70d67 100644
--- a/src/java/org/apache/fop/apps/FopFactory.java
+++ b/src/java/org/apache/fop/apps/FopFactory.java
@@ -24,7 +24,6 @@ import java.io.File;
 import java.io.IOException;
 import java.io.OutputStream;
 import java.net.MalformedURLException;
-import java.net.URISyntaxException;
 import java.net.URL;
 import java.util.Collection;
 import java.util.Collections;
@@ -195,7 +194,7 @@ public class FopFactory implements ImageContext {
      * @throws FOPException when the constructor fails
      */
     public Fop newFop(String outputFormat) throws FOPException {
-        return new Fop(outputFormat, newFOUserAgent());
+        return newFop(outputFormat, newFOUserAgent());
     }
 
     /**
@@ -212,10 +211,7 @@ public class FopFactory implements ImageContext {
      * @throws FOPException  when the constructor fails
      */
     public Fop newFop(String outputFormat, FOUserAgent userAgent) throws FOPException {
-        if (userAgent == null) {
-            throw new NullPointerException("The userAgent parameter must not be null!");
-        }
-        return new Fop(outputFormat, userAgent);
+        return newFop(outputFormat, userAgent, null);
     }
     
     /**
@@ -230,7 +226,7 @@ public class FopFactory implements ImageContext {
      * @throws FOPException when the constructor fails
      */
     public Fop newFop(String outputFormat, OutputStream stream) throws FOPException {
-        return new Fop(outputFormat, newFOUserAgent(), stream);
+        return newFop(outputFormat, newFOUserAgent(), stream);
     }
 
     /**
@@ -333,11 +329,10 @@ public class FopFactory implements ImageContext {
     }
 
     /**
-     * cleans the base url
-     * @param base
-     * @return
-     * @throws MalformedURLException
-     * @throws URISyntaxException 
+     * Checks if the given base URL is acceptable. It also normalizes the URL.
+     * @param base the base URL to check
+     * @return the normalized URL
+     * @throws MalformedURLException if there's a problem with a file URL
      */
     private String checkBaseURL(String base) throws MalformedURLException {
         if (!base.endsWith("/")) {
@@ -364,8 +359,7 @@ public class FopFactory implements ImageContext {
     /**
      * Sets the base URL.
      * @param base base URL
-     * @throws MalformedURLException 
-     * @throws URISyntaxException 
+     * @throws MalformedURLException if there's a problem with a file URL
      */
     public void setBaseURL(String base) throws MalformedURLException {
         this.base = checkBaseURL(base);
@@ -382,8 +376,7 @@ public class FopFactory implements ImageContext {
     /**
      * Sets the font base URL.
      * @param fontBase font base URL
-     * @throws MalformedURLException 
-     * @throws URISyntaxException 
+     * @throws MalformedURLException if there's a problem with a file URL
      */
     public void setFontBaseURL(String fontBase) throws MalformedURLException {
         this.fontBase = checkBaseURL(fontBase);
@@ -402,8 +395,7 @@ public class FopFactory implements ImageContext {
     /**
      * Sets the hyphen base URL.
      * @param hyphenBase hythen base URL
-     * @throws MalformedURLException 
-     * @throws URISyntaxException 
+     * @throws MalformedURLException if there's a problem with a file URL
      * */
     public void setHyphenBaseURL(final String hyphenBase) throws MalformedURLException {
         if (hyphenBase != null) {
@@ -440,8 +432,8 @@ public class FopFactory implements ImageContext {
     }
     
     /**
-     * sets the HyphenationTreeResolver
-     * @param hyphResolver
+     * Sets the HyphenationTreeResolver to be used for resolving user-supplied hyphenation files.
+     * @param hyphResolver the HyphenationTreeResolver instance
      */
     public void setHyphenationTreeResolver(HyphenationTreeResolver hyphResolver) {
         this.hyphResolver = hyphResolver;
@@ -724,6 +716,10 @@ public class FopFactory implements ImageContext {
         return (this.fontCache != null);
     }
 
+    /**
+     * Returns the font cache instance used by this factory.
+     * @return the font cache
+     */
     public FontCache getFontCache() {
         return this.fontCache;
     }