Fixed deprecation warning and added some comments to explain the API design

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

src/java/org/apache/fop/apps/FopFactoryBuilder.java

@@ -97,6 +97,17 @@ public final class FopFactoryBuilder {
      * @deprecated Exposing the {@link FopFactoryConfig} is only to maintain backwards compatibility
      */
     public FopFactoryConfig buildConfig() {
+        return buildConfiguration();
+    }
+
+    /**
+     * Builds the configuration object used by the FopFactory.
+     *
+     * @return the config for the {@link FopFactory}
+     */
+    // The {@link FopFactoryConfig} doesn't need to be exposed in the "public" API, this method
+    // should remain package private.
+    FopFactoryConfig buildConfiguration() {
         fopFactoryConfigBuilder = CompletedFopFactoryConfigBuilder.INSTANCE;
         return config;
     }
@@ -107,7 +118,7 @@ public final class FopFactoryBuilder {
      * @return the FopFactory instance
      */
     public FopFactory build() {
-        return FopFactory.newInstance(buildConfig());
+        return FopFactory.newInstance(buildConfiguration());
     }
 
     /**

src/java/org/apache/fop/apps/FopFactoryConfig.java

@@ -34,6 +34,9 @@ import org.apache.fop.layoutmgr.LayoutManagerMaker;
 /**
  * The configuration data for a {@link FopFactory} instance.
  */
+// TODO: Make this interface and any implementations of this interface package private. Though
+// they are used by classes that are considered the public API, this object doesn't need to be a
+// part of the API. Why would a user care how the internal objects are passed around? They shouldn't.
 public interface FopFactoryConfig {
 
     /** Defines if FOP should use an alternative rule to determine text indents */

test/java/org/apache/fop/apps/FopFactoryBuilderTestCase.java

@@ -162,7 +162,7 @@ public class FopFactoryBuilderTestCase {
             public void run() {
                 URI nonDefaultURI = URI.create("./test/");
                 defaultBuilder.setBaseURI(nonDefaultURI);
-                assertEquals(nonDefaultURI, defaultBuilder.buildConfig().getBaseURI());
+                assertEquals(nonDefaultURI, defaultBuilder.buildConfiguration().getBaseURI());
             }
         });
     }

test/java/org/apache/fop/apps/MutableConfig.java

@@ -0,0 +1,133 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements.  See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License.  You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.apache.fop.apps;
+
+import java.net.URI;
+import java.util.Map;
+import java.util.Set;
+
+import org.apache.avalon.framework.configuration.Configuration;
+
+import org.apache.xmlgraphics.image.loader.ImageManager;
+
+import org.apache.fop.apps.io.ResourceResolver;
+import org.apache.fop.fonts.FontManager;
+import org.apache.fop.layoutmgr.LayoutManagerMaker;
+
+/**
+ * This is a mutable implementation of the {@link FopFactoryConfig} to be used for testing purposes.
+ * This is also an example of how to make the seemingly immutable {@link FopFactory} mutable should
+ * a client need to, though this is ill-advised.
+ */
+public final class MutableConfig implements FopFactoryConfig {
+
+    private final FopFactoryConfig delegate;
+
+    private boolean setBreakInheritance;
+    private float sourceResolution;
+
+    public MutableConfig(FopFactoryBuilder factoryBuilder) {
+        delegate = factoryBuilder.buildConfiguration();
+        setBreakInheritance = delegate.isBreakIndentInheritanceOnReferenceAreaBoundary();
+        sourceResolution = delegate.getSourceResolution();
+    }
+
+    public boolean isAccessibilityEnabled() {
+        return delegate.isAccessibilityEnabled();
+    }
+
+    public LayoutManagerMaker getLayoutManagerMakerOverride() {
+        return delegate.getLayoutManagerMakerOverride();
+    }
+
+    public ResourceResolver getResourceResolver() {
+        return delegate.getResourceResolver();
+    }
+
+    public URI getBaseURI() {
+        return delegate.getBaseURI();
+    }
+
+    public boolean validateStrictly() {
+        return delegate.validateStrictly();
+    }
+
+    public boolean validateUserConfigStrictly() {
+        return delegate.validateUserConfigStrictly();
+    }
+
+    public boolean isBreakIndentInheritanceOnReferenceAreaBoundary() {
+        return setBreakInheritance;
+    }
+
+    public void setBreakIndentInheritanceOnReferenceAreaBoundary(boolean value) {
+        setBreakInheritance = value;
+    }
+
+    public float getSourceResolution() {
+        return sourceResolution;
+    }
+
+    public void setSourceResolution(float srcRes) {
+        sourceResolution = srcRes;
+    }
+
+    public float getTargetResolution() {
+        return delegate.getTargetResolution();
+    }
+
+    public String getPageHeight() {
+        return delegate.getPageHeight();
+    }
+
+    public String getPageWidth() {
+        return delegate.getPageWidth();
+    }
+
+    public Set<String> getIgnoredNamespaces() {
+        return delegate.getIgnoredNamespaces();
+    }
+
+    public boolean isNamespaceIgnored(String namespace) {
+        return delegate.isNamespaceIgnored(namespace);
+    }
+
+    public Configuration getUserConfig() {
+        return delegate.getUserConfig();
+    }
+
+    public boolean preferRenderer() {
+        return delegate.preferRenderer();
+    }
+
+    public FontManager getFontManager() {
+        return delegate.getFontManager();
+    }
+
+    public ImageManager getImageManager() {
+        return delegate.getImageManager();
+    }
+
+    public boolean isComplexScriptFeaturesEnabled() {
+        return delegate.isComplexScriptFeaturesEnabled();
+    }
+
+    public Map<String, String> getHyphenationPatternNames() {
+        return delegate.getHyphenationPatternNames();
+    }
+}

test/java/org/apache/fop/fotreetest/FOTreeTestCase.java

@@ -20,11 +20,8 @@
 package org.apache.fop.fotreetest;
 
 import java.io.File;
-import java.net.URI;
 import java.util.Collection;
 import java.util.List;
-import java.util.Map;
-import java.util.Set;
 
 import javax.xml.parsers.SAXParser;
 import javax.xml.parsers.SAXParserFactory;
@@ -38,22 +35,16 @@ import org.xml.sax.SAXException;
 import org.xml.sax.XMLReader;
 import org.xml.sax.helpers.XMLFilterImpl;
 
-import org.apache.avalon.framework.configuration.Configuration;
-
-import org.apache.xmlgraphics.image.loader.ImageManager;
-
 import org.apache.fop.DebugHelper;
 import org.apache.fop.apps.FOUserAgent;
 import org.apache.fop.apps.Fop;
 import org.apache.fop.apps.FopFactory;
 import org.apache.fop.apps.FopFactoryBuilder;
 import org.apache.fop.apps.FopFactoryConfig;
-import org.apache.fop.apps.io.ResourceResolver;
-import org.apache.fop.fonts.FontManager;
+import org.apache.fop.apps.MutableConfig;
 import org.apache.fop.fotreetest.ext.TestElementMapping;
 import org.apache.fop.layoutengine.LayoutEngineTestUtils;
 import org.apache.fop.layoutengine.TestFilesConfiguration;
-import org.apache.fop.layoutmgr.LayoutManagerMaker;
 import org.apache.fop.util.ConsoleEventListenerForTests;
 
 /**
@@ -123,7 +114,7 @@ public class FOTreeTestCase {
                    FopFactoryConfig.DEFAULT_BREAK_INDENT_INHERITANCE);
             builder.setSourceResolution(FopFactoryConfig.DEFAULT_SOURCE_RESOLUTION);
 
-            MutableConfig mutableConfig = new MutableConfig(builder.buildConfig());
+            MutableConfig mutableConfig = new MutableConfig(builder);
 
             FopFactory fopFactory = FopFactory.newInstance(mutableConfig);
             fopFactory.addElementMapping(new TestElementMapping());
@@ -181,102 +172,4 @@ public class FOTreeTestCase {
             super.processingInstruction(target, data);
         }
     }
-
-    private static final class MutableConfig implements FopFactoryConfig {
-
-        private final FopFactoryConfig delegate;
-
-        private boolean setBreakInheritance;
-        private float sourceResolution;
-
-        private MutableConfig(FopFactoryConfig wrappedConfig) {
-            delegate = wrappedConfig;
-            setBreakInheritance = delegate.isBreakIndentInheritanceOnReferenceAreaBoundary();
-            sourceResolution = delegate.getSourceResolution();
-        }
-
-        public boolean isAccessibilityEnabled() {
-            return delegate.isAccessibilityEnabled();
-        }
-
-        public LayoutManagerMaker getLayoutManagerMakerOverride() {
-            return delegate.getLayoutManagerMakerOverride();
-        }
-
-        public ResourceResolver getResourceResolver() {
-            return delegate.getResourceResolver();
-        }
-
-        public URI getBaseURI() {
-            return delegate.getBaseURI();
-        }
-
-        public boolean validateStrictly() {
-            return delegate.validateStrictly();
-        }
-
-        public boolean validateUserConfigStrictly() {
-            return delegate.validateUserConfigStrictly();
-        }
-
-        public boolean isBreakIndentInheritanceOnReferenceAreaBoundary() {
-            return setBreakInheritance;
-        }
-
-        public void setBreakIndentInheritanceOnReferenceAreaBoundary(boolean value) {
-            setBreakInheritance = value;
-        }
-
-        public float getSourceResolution() {
-            return sourceResolution;
-        }
-
-        public void setSourceResolution(float srcRes) {
-            sourceResolution = srcRes;
-        }
-
-        public float getTargetResolution() {
-            return delegate.getTargetResolution();
-        }
-
-        public String getPageHeight() {
-            return delegate.getPageHeight();
-        }
-
-        public String getPageWidth() {
-            return delegate.getPageWidth();
-        }
-
-        public Set<String> getIgnoredNamespaces() {
-            return delegate.getIgnoredNamespaces();
-        }
-
-        public boolean isNamespaceIgnored(String namespace) {
-            return delegate.isNamespaceIgnored(namespace);
-        }
-
-        public Configuration getUserConfig() {
-            return delegate.getUserConfig();
-        }
-
-        public boolean preferRenderer() {
-            return delegate.preferRenderer();
-        }
-
-        public FontManager getFontManager() {
-            return delegate.getFontManager();
-        }
-
-        public ImageManager getImageManager() {
-            return delegate.getImageManager();
-        }
-
-        public boolean isComplexScriptFeaturesEnabled() {
-            return delegate.isComplexScriptFeaturesEnabled();
-        }
-
-        public Map<String, String> getHyphenationPatternNames() {
-            return delegate.getHyphenationPatternNames();
-        }
-    }
 }