/*
*
* 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.flex.compiler.targets;
import java.io.File;
import java.util.Collection;
import java.util.List;
import java.util.Map;
import org.apache.flex.compiler.config.RSLSettings;
import org.apache.flex.compiler.internal.config.FrameInfo;
/**
* The settings used to compile a target.
*/
public interface ITargetSettings
{
/**
* Returns true if the target file is accessible.
*
* @return true if the target file is accessible, false otherwise.
*/
boolean isAccessible();
/**
* Returns true if the target file has debugging instructions
* included.
* @return true if the target file has debugging instructions
* included, false otherwise.
*/
boolean isDebugEnabled();
/**
* Returns true if the target file has advanced telemetry
* enabled.
* @return true if the target file has advanced telemetry
* enabled, false otherwise.
*/
boolean isTelemetryEnabled();
/**
* Returns true if the target should be optimized.
*
* @return true if the target should be optimized, false otherwise.
*/
boolean isOptimized();
/**
* Returns true if the target should be output using compression.
*
* @return true if the target should be output using compression, false
* otherwise.
*/
boolean useCompression();
/**
* Returns true if the target is capable of verbose stack traces.
*
* @return true if the target is capable of verbose stack traces,
* false otherwise.
*/
boolean areVerboseStacktracesEnabled();
/**
* The names of ActionScript metadata that will be preserved in the target.
* If the target is a SWC, the metadata names to preserve will be
* recorded in the SWC's catalog. When the SWC is later linked into
* a target the metadata names will be appended to the list of metadata
* names preserved in the target.
*
* @return the list of names of ActionScript metadata that will be
* preserved in the target. If null, all metadata is preserved.
*/
Collection<String> getASMetadataNames();
/**
* Returns the location of the default CSS file.
*
* @return an instance of <code>java.io.File</code>.
*/
File getDefaultCSS();
/**
* @return Normalized paths in {@code defaults-css-files} configuration option.
*/
List<String> getDefaultsCSSFiles();
/**
* @return Normalized paths in {@code exclude-defaults-css-files} configuration option.
*/
List<String> getExcludeDefaultsCSSFiles();
/**
* Returns the default background color.
*
* @return the default background color.
*/
int getDefaultBackgroundColor();
/**
* Returns the default frame rate.
*
* @return the default frame rate in frames per second.
*/
int getDefaultFrameRate();
/**
* Returns if the default script limits have been set.
*
* @return true if limits set, false otherwise.
*/
boolean areDefaultScriptLimitsSet();
/**
* Returns the default script time limit.
*
* @return the default script time limit in seconds.
*/
int getDefaultScriptTimeLimit();
/**
* Returns the default script recursion limit.
*
* @return the default script recursion limit.
*/
int getDefaultScriptRecursionLimit();
/**
* Returns the default width.
*
* @return the default width in pixels.
*/
int getDefaultWidth();
/**
* Returns the default height.
*
* @return the default height in pixels.
*/
int getDefaultHeight();
/**
* Returns a list of fully qualified class names that should not be linked
* into the target.
*
* @return a list of fully qualified class names that should not be linked
* into the target.
*/
Collection<String> getExterns();
/**
* Returns a list of fully qualified class names that should be linked
* into the target regardless of whether they are required by the target or
* not.
*
* @return a list of fully qualified class names that should be linked
* into the target.
*/
Collection<String> getIncludes();
/**
* A {@link List} of {@link FrameInfo} objects that describe extra frames of
* a SWF. Each frame label has a list of class names that will be linked
* onto the frame.
*
* @return A collection of {@link FrameInfo} objects in SWF order.
*/
List<FrameInfo> getFrameLabels();
/**
* Get the Metadata text. This is a Metadata property.
* <p>
* The Metadata tag is an optional tag to describe the SWF file to an
* external process. The tag embeds XML metadata in the SWF file so that,
* for example, a search engine can locate this tag, access a title for the
* SWF file, and display that title in search results.
*
* @return metadata XML text; null if Metadata tag doesn't exit.
*/
String getSWFMetadata();
/**
* Return the SWF version
*
* @return SWF version
*/
int getSWFVersion();
/**
* Returns the preloader class name
*
* @return preloader class name
*/
String getPreloaderClassName();
/**
* Returns the absolute file name of the source file that defines the root
* class. If {@link ITarget}s using this {@link ITargetSettings} do not
* build SWFs ( they could build SWCs instead ), then this method will
* return null.
*
* @return absolute file name of the source file that defines the root
* class, or null if this {@link ITargetSettings} is not for building SWFs.
*/
String getRootSourceFileName();
/**
* Returns the root class name for the application SWF. If {@link ITarget}s
* using this {@link ITargetSettings} do not build SWFs ( they could build
* SWCs instead ), then this method will return null.
*
* @return rootClassName of the application SWF, or null if this
* {@link ITargetSettings} is not for building SWFs.
*/
String getRootClassName();
/**
* Returns true if the compiler has disabled the pruning of unused type
* selectors.
*
* @return true if the compiler has disabled the pruning of unused type
* selectors, false otherwise.
*/
boolean keepAllTypeSelectors();
/**
* Returns whether the application SWF is flagged for access to network
* resources.
*
* @return true if the application SWF is flagged for access to network
* resources, false otherwise.
*/
boolean useNetwork();
/**
* Returns whether the application is comprised of code that used
* subclass overrides.
*
* @return true if the application is comprised of code that used
* subclass overrides, false otherwise.
*/
boolean allowSubclassOverrides();
/**
* Returns a list of CSS and SWC files to apply as a theme.
*
* @return a list of CSS and SWC files to apply as a theme.
*/
List<File> getThemes();
/**
* Returns true if RSLs that have no classes used by the application are
* not loaded at runtime.
*
* @return true if RSLs that have no classes used by the application are
* not loaded at runtime, false otherwise.
*/
boolean removeUnusedRuntimeSharedLibraryPaths();
/**
* Returns the default setting for all RSLs as to whether an RSL's digest
* should be verified after the RSL is loaded. This setting may be overridden
* by setting the verify digest flag on an individual RSL.
*
* This is equivalent to using the <code>verify-digests</code>
* option in the mxmlc compiler.
*
* @see org.apache.flex.compiler.config.RSLSettings
*/
boolean verifyDigests();
/**
* Returns a collection of libraries whose classes are not be linked
* into the target.
*
* @return a collection of libraries whose classes are not be linked
* into the target.
*/
Collection<File> getExternalLibraryPath();
/**
* Returns a collection of libraries whose classes are linked
* into the target. All the of classes in each library are linked
* into the application regardless of whether the classes is referenced
* by the target.
*
* @return a collection of libraries whose classes will be linked
* into the target.
*/
Collection<File> getIncludeLibraries();
/**
* A list of URLs pointing to RSLs to load. The RSLs will be loaded in the
* order that they appear in the list.
*
* This is equivalent to using the <code>runtime-shared-libraries</code>
* option in the mxmlc compiler.
*
* These RSLs are available to support legacy applications. For the latest
* RSL support see getRuntimeSharedLibraryPath.
*
* @return A list of URLs pointing to RSLs to load.
*/
List<String> getRuntimeSharedLibraries();
/**
* A list of RSLs to load, complete with all the settings on how to load
* the RSLs. The RSLs will be loaded in the order that they appear in the
* list. This is the complete list of RSLs that could possibly be loaded.
* This list could be reduced if unused RSLs are being removed.
*
* This is equivalent to using the <code>runtime-shared-library-path</code>
* option in the mxmlc compiler.
* @return A list of RSLs to load.
*/
List<RSLSettings> getRuntimeSharedLibraryPath();
/**
* Returns true if resource bundle metadata should be processed.
*
* @return true if resource bundle metadata should be processed, false otherwise.
*/
boolean useResourceBundleMetadata();
/**
* Returns the file that specifies where the target should be created.
*
* @return the file that specifies where the target should be created.
*/
File getOutput();
/**
* Returns the file that specifies where the link report should be written.
*
* @return the file that specifies where the link report should be written
* or null if the link report was not requested.
*/
File getLinkReport();
/**
* Returns the file that specifies where the size report should be written.
*
* @return the file that specifies where the size report should be written
* or null if the size report was not requested.
*/
File getSizeReport();
//
// Library specific settings
//
/**
* Returns a collection of fully-qualified class names that are included in
* the target library.
*
* @return a collection of fully-qualified class names that are included in
* the target library.
*/
Collection<String> getIncludeClasses();
/**
* Returns a collection of sources that are included in the target library.
*
* @return a collection of sources that are included in the target library.
*/
Collection<File> getIncludeSources();
/**
* Returns a collection of files that are included in the target library.
* Each entry in the map is a file to be included. The key is the name
* of the file in the target library. The value is the file to be included
* in the library.
*
* @return a collection of files that are included in the target library.
*/
Map<String, File> getIncludeFiles();
/**
* Returns a collection of namespaces that are included in the target
* library.
*
* @return a collection of namespaces that are included in the target
* library.
*/
Collection<String> getIncludeNamespaces();
/**
* Returns a collection of resource bundle names that are included
* in the target library.
*
* @return a collection of resource bundle names that are included
* in the target library.
*/
Collection<String> getIncludeResourceBundles();
/**
* Returns a map of style sheet names and files that are included
* in the target library.
*
* The map's key/value pairs are as follows:
* key: the name of the file in the target library
* value: the included style sheet.
* @return a collection of style sheet names and files that are included
* in the target library.
*/
Map<String, File> getIncludeStyleSheets();
/**
* Returns true if only manifest entries with lookupOnly=true are included
* in the SWC catalog, false otherwise.
*
* @return true if only manifest entries with lookupOnly=true are included
* in the SWC catalog, false otherwise.
*/
boolean isIncludeLookupOnlyEnabled();
/**
* Determine is a library has external linkage. A library with external
* linkage will have none of its classes appear in the target. Two exceptions
* to this rule are classes on the -include-classes option and classes that
* are linked into frames preceding the last frame of SWF.
*
* @param path the absolute path of a library.
*
* @return true if the library has external linkage.
*/
boolean isLinkageExternal(String path);
/**
* Returns whether the application SWF is flagged for direct blit use.
*
* @return true if the application SWF should use direct blit, false otherwise.
*/
boolean useDirectBlit();
/**
* Returns whether the application SWF is flagged for GPU use.
*
* @return true if the application SWF should use the GPU, false otherwise.
*/
boolean useGPU();
/**
* Used when creating a library. Specifies the minimum version of Flex that
* is written into the catalog of the created library. Flex uses the minimum
* version when compiling an application to filter out libraries that have a
* minimum version that is greater than the specified compatibility
* version.
*
* @return the minimum supported version of Flex.
*/
String getFlexMinimumSupportedVersion();
/**
* @return true if MXML child nodes are encoded into a data stream instead
* of a bunch of functions.
*/
boolean getMxmlChildrenAsData();
/**
* @return true if the info() structure should contain fields needed by FlexSDK only (and not FlexJS).
*/
boolean getInfoFlex();
/**
* @return true if the return type of an override can be a subclass instead
* of an exact match as the base class' return type
*/
boolean getAllowSubclassOverrides();
/**
* @return true if the dead code filtering optimization step is enabled.
*/
boolean getRemoveDeadCode();
/**
* Gets the implicit imports for MXML.
*
* @return An array of strings specifying the import targets.
*/
String[] getMxmlImplicitImports();
}