com.google.api.tools.framework.model

Interface ConfigAspect

All Known Implementing Classes:

AuthConfigAspect, ConfigAspectBase, ContextConfigAspect, ControlConfigAspect, DocumentationConfigAspect, HttpConfigAspect, MixinConfigAspect, NamingConfigAspect, RuleBasedConfigAspect, ServiceControlConfigAspect, SystemConfigAspect, SystemParameterConfigAspect, UsageConfigAspect, VersionConfigAspect

public interface ConfigAspect

Represents an abstraction of a configuration cross-cut, like documentation, http, auth, etc. In order to integrate a configuration aspect into the system, this interface should not be directly implemented, instead extend one of the abstract base classes implementing this interface in the aspects package.

Processing of aspects is performed in three phases:

1. Merging: During this phase the configuration is merged with the protocol definition. Essential validation of the configuration is performed, and errors are reported. Attributes may be added to the model representing information relevant to the aspect.
2. Linting (style checking): During this phase, additional, non-essential validation is performed on the model. This phase is optional and produces warnings.
3. Normalization: In this phase the configuration is re-build in a normalized form, as it is expected by downstream tools.

Each phase is preluded by a method call to indicate its start, followed by a call to each model element, followed by a call indicating the end of the phase.

Config aspects can communicate with each other by attaching attributes to the model. Attributes are usually synthesized during the merging phase. If one aspect depends on another's attributes in the merging phase, the dependency must be specified using the mergeDependencies() method.

Method Summary

Modifier and Type	Method and Description
void	endLinting() Marks end of style checking.
void	endMerging() Marks end of merging.
void	endNormalization(com.google.api.Service.Builder builder) Marks end of normalization.
java.lang.String	getAspectName() Returns the string identifying the aspect in diagnosis.
java.lang.String	getDocumentation(ProtoElement element) The configuration aspect documentation for the proto element.
java.lang.String	getDocumentationTitle(ProtoElement element) The title of the configuration aspect documentation for given proto element.
java.util.Set<java.lang.String>	getLintRuleNames() Returns the set of all style rule names related to this aspect.
void	lint(ProtoElement element) Style checks the given element.
void	merge(ProtoElement element) Merges the config aspect with the given proto element.
java.util.List<java.lang.Class<? extends ConfigAspect>>	mergeDependencies() Returns the types of aspects which must be run before this aspect during the merging phase.
void	normalize(ProtoElement element, com.google.api.Service.Builder builder) Normalizes the service config w.r.t.
void	startLinting() Marks the begin of style checking.
void	startMerging() Marks start of merging.
void	startNormalization(com.google.api.Service.Builder builder) Marks start of normalization.

Method Detail

getAspectName

java.lang.String getAspectName()

Returns the string identifying the aspect in diagnosis.

getLintRuleNames

java.util.Set<java.lang.String> getLintRuleNames()

Returns the set of all style rule names related to this aspect.

mergeDependencies

java.util.List<java.lang.Class<? extends ConfigAspect>> mergeDependencies()

Returns the types of aspects which must be run before this aspect during the merging phase.

startMerging

void startMerging()

Marks start of merging. Can be used to merge model-global config and prepare merging.

merge

void merge(ProtoElement element)

Merges the config aspect with the given proto element. This will be called for each element of the model during the merging phase, breadth first. The config aspect decides whether it is applicable for the element, performs merging, potentially reporting diagnostics on the model, and attaching attributes via Element.putAttribute(com.google.inject.Key, Object).

endMerging

void endMerging()

Marks end of merging. Can be used to do post-merging validation.

startLinting

void startLinting()

Marks the begin of style checking.

lint

void lint(ProtoElement element)

Style checks the given element. This will be called for each element, breadth first.

endLinting

void endLinting()

Marks end of style checking.

startNormalization

void startNormalization(com.google.api.Service.Builder builder)

Marks start of normalization. For normalization, the original service definition will be passed in as a builder; this call can be used to clear any data related to this aspect before adding it back in normalized form.

normalize

void normalize(ProtoElement element,
               com.google.api.Service.Builder builder)

Normalizes the service config w.r.t. to this aspect. Will be called for each element in the model during normalization phase. If the config type has applicable aspects for the element it can update the service config with normalized and derived data.

endNormalization

void endNormalization(com.google.api.Service.Builder builder)

Marks end of normalization. Can be used to do cleanup.

getDocumentationTitle

@Nullable
java.lang.String getDocumentationTitle(ProtoElement element)

The title of the configuration aspect documentation for given proto element. This is called only after the merging phase has successfully concluded for the whole model. Return null to indicate that no documentation is available.

getDocumentation

@Nullable
java.lang.String getDocumentation(ProtoElement element)

The configuration aspect documentation for the proto element. The documentation should be in Markdown format. This is called only after the merging phase has successfully concluded for the whole model. Return null to indicate no documentation is available.