OutputGenerator class reference
NSObject | |
OutputProcessing OutputInfoProvider |
|
OutputGenerator.h |
Overview
Defines the basics for an output generator.
Output generators are objects that generate final output from intermediate files. Each type of supported output is implemented by a concrete subclass. This class should be treated as abstract base class. It provides the stubs for the output generation which should be overriden by subclasses to implement the required functionality. Output generators conform to OutputProcessing
and OutputInfoProvider
formal protocols. The OutputProcessing
protocol is fully implemented, however the subclasses need to override -[OutputInfoProvider outputFilesExtension]
and return proper value. Default implementation returns empty string. The rest of the OutputInfoProvider
methods should generally be correctly implemented by the base class though.
Additionally, output generators also support tree-like generation of dependent generators. This allows simple handling of dependent generation and eliminates the worry of when to start certain dependent generator, when to remove temporary files etc. Dependent generators must be registered prior than starting the actual generation. Registration is performed by sending the receiver - registerDependentGenerator:
message. Note that clients are responsible for setting up dependencies, OutputGenerator
objects then handle all dependent generators at proper time.
OutputGenerator
is an abstract base class. Concrete subclasses should implement their specifics within the following overrides:
- generateSpecificOutput
: concrete subclasses should override this method and generate their specific output based on their promise. This message is sent from-[OutputProcessing generateOutput]
which takes care of handling dependencies and directories creation and removal among other things. So in general, subclasses should not override-[OutputProcessing generateOutput]
.
Note that the OutputGenerator
base class provides some helper variables to prevent repetition and allow less cluttered code in the concrete subclasses. These include:
manager:
Set to the[NSFileManager defaultManager]
.cmd:
Set to the+[CommandLineParser sharedInstance]
.database:
Set to the main objects database (set through theinitWithDatabase:
).
Tasks
Initialization & disposal
-
- initWithDatabase:
Initializes the output generator.
Dependencies handling
-
- registerDependentGenerator:
Registers the given dependent generator and adds it to the end of the dependent generators list.
Output generation entry points
-
- outputGenerationStarting
Notifies output generator that generation is starting. -
- outputGenerationFinished
Notifies output generator that generation is finished. -
- generateSpecificOutput
Notifies concrete output generator subclass to start processing the data and generate output.
Output directories handling
-
- createOutputDirectories
Creates all required output directories. -
- removeOutputDirectories
Removes all output directories and files.
Helper methods
-
- pathByReplacingTemplatePlaceholdersInPath:
Creates a new NSString by replacing path placeholders in the given template path.
Instance methods
initWithDatabase:
Initializes the output generator.
- (id)initWithDatabase:(NSMutableDictionary *) data
Parameters
- data
The main database of objects which is used for creating output. The value is retained by the initializer, so all instances should be released when no longer used.
Exceptions
- NSException
Thrown if the given database is
nil
or initialization fails.
Return value
Returns initialized object or nil
if initialization fails.
Discussion
This is the designated initializer. It maps the main objects database so it is accessible for subclasses.
Important: Note that the some concrete subclasses actually create the data in the database, while others only use it. Therefore it is important that the generation is invoked in the proper order. This is one of the points where clients should be aware of the proper order of creation and how different output generator subclasses are linked together.
Declared in
OutputGenerator.h
registerDependentGenerator:
Registers the given dependent generator and adds it to the end of the dependent generators list.
- (void)registerDependentGenerator:(id) generator
Parameters
- generator
The
OutputProcessing
subclass which depends on this generator.
Exceptions
- NSException
Thrown if the given
generator
isnil
.
Discussion
After dependent generator is registered, it is automaticallty handled, so clients don't have to manually invoke it's output generation. Furthermore, removal of temporary files is also automatically handled at proper time. Note that the given generator may in turn have more dependent generators registered - output generation recursively invokes generation in proper order. At this point, generators cannot be unregistered!
Note that all dependent generators must be registered before generating the output for the receiver (i.e. before sending -[OutputProcessing generateOutput]
message).
Declared in
OutputGenerator.h
outputGenerationStarting
Notifies output generator that generation is starting.
- (void)outputGenerationStarting
Discussion
This message is sent after previous output generator finishes but before the concrete output generator starts processing the data. Subclasss can use it to setup initial values if for example. When the receiver returns from the method, -[OutputProcessing generateOutput]
is sent, followed by - outputGenerationFinished
.
Important:
Note that implementors
See also
Declared in
OutputGenerator.h
outputGenerationFinished
Notifies output generator that generation is finished.
- (void)outputGenerationFinished
Exceptions
- NSException
Thrown if errors are detected while finalizing output generation.
Discussion
This message is sent after the concrete output generator processing ends but before next generator starts processing the data. Subclasss can use it to cleanup after processing or to perform final tasks which depend on the processing results.
See also
Declared in
OutputGenerator.h
generateSpecificOutput
Notifies concrete output generator subclass to start processing the data and generate output.
- (void)generateSpecificOutput
Exceptions
- NSException
Thrown if output generation fails.
Discussion
This message is sent after - createOutputDirectories
and - outputGenerationStarting
. The concrete subclass should only handle it's specific output generation. After the subclass returns, - outputGenerationFinished
is sent. If any dependent generator is assigned, their output generation is issued afterwards. And when all dependent generators finish, - removeOutputDirectories
is sent if temporary files should be removed.
See also
Declared in
OutputGenerator.h
createOutputDirectories
Creates all required output directories.
- (void)createOutputDirectories
Exceptions
- NSException
Thrown if directories creation fails.
Discussion
This message is sent before any output generation begins if the subclass returns @ YES from isOutputGenerationEnabled
. Subclasses should create all directories they require. If any of the required directories already exists, the subclass should decide on whether it should delete it or skip it. In most cases, the directory is left as is. If the directory contains files, the subclass should again decide whether it should remove these or leave them. Again, in most cases the files can be left as they are.
Default implementation creates the path returned from -[OutputInfoProvider outputBasePath]
and all default subdirectories: Classes
, Categories
and Protocols
. Subclasses that need to create additional directories or don't want to use default ones, should override and create all required directories themselves.
See also
Declared in
OutputGenerator.h
removeOutputDirectories
Removes all output directories and files.
- (void)removeOutputDirectories
Exceptions
- NSException
Thrown if removing directories or files fails.
Discussion
This message is sent after all concrete output generators finish their jobs if temporary files should be removed or before generation starts if clean run is desired. Subclasses should remove all generated directories and files. Note that this message is only sent if - createOutputDirectories
was sent at the start of the generation.
Default implementation removes the directory at the path returned from -[OutputInfoProvider outputBasePath]
. Subclasses that need to remove additional directories should override and remove all directories created in - createOutputDirectories
. This should be vary rare though.
See also
Declared in
OutputGenerator.h
pathByReplacingTemplatePlaceholdersInPath:
Creates a new NSString
by replacing path placeholders in the given template path.
- (NSString *)pathByReplacingTemplatePlaceholdersInPath:(NSString *) path
Parameters
- path
The template path in which to replace placeholders.
Return value
Returns an autoreleased NSString
containing correct path.
Declared in
OutputGenerator.h
© 2008-2009 Tomaz Kragelj. All rights reserved. (Last updated: 2009-08-24)
Back to index / hierarchy.