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:

Note that the OutputGenerator base class provides some helper variables to prevent repetition and allow less cluttered code in the concrete subclasses. These include:

Tasks

Initialization & disposal

Dependencies handling

Output generation entry points

Output directories handling

Helper methods

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 is nil.

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.