Syntax

   FACTORY_DEF <ReaderKeyword> GML2Factory
   [FACTORY_NAME <factory name>]
   [INPUT FEATURE_TYPE <feature type>
      [<attribute name> <attribute value>]*
      [<feature function>]*]*
   GML2_DATA_ATTR <attribute name>
   DIRECTION (READ|WRITE)
   [MERGE_ATTRIBUTES (TRUE|FALSE)]
   [MERGE_PREFIX <string prefix>]
   [BREAK_BEFORE_FIELD_CHANGE [<attribute name>]+]
   [BREAK_AFTER_FIELD_CHANGE [<attribute name>]+]
   [END_CURRENT_WHEN <value> <operator> <value>]+  // not implemented yet      
   [START_NEW_WHEN <value> <operator> <value>]+    // not implemented yet              
   [FAIL_IF_INVALID_GML (TRUE|FALSE)]
   [XFMAP <xfMap file>]
   [FEATURE_NUMBER <attribute name>]
   [FEATURE_ID <attribute name>]
   [OUTPUT (ORIGINAL|GML2|INVALID_GML) 
      FEATURE_TYPE <feature type> 
      [<attribute name> <attribute value>]*
      [<feature function>]*]*

Overview

   This factory is used to construct features out of GML2 documents that are 
   stored in an attribute of the input features. It can also be used to 
   construct GML2 documents from features. The DIRECTION clause specifies the 
   factory's mode of operation. 

   When the DIRECTION is READ, the factory constructs FME features from GML2 
   documents. The GML2 documents are expected to be stored in an attribute of 
   the input features; the GML_DATA_ATTR clause specifies the name of this 
   attribute. The original feature is output untouched via the OUTPUT ORIGINAL 
   FEATURE_TYPE clause, while features from the GML2 document are output via the 
   OUTPUT GML2 FEATURE_TYPE clause. The INVALID_GMLFEATURE_TYPE clause outputs 
   features whose GML_DATA_ATTR clause contains invalid GML2.

   The factory also contains optional clauses that specify additional attributes 
   for features output by the OUTPUT GML2 FEATURE_TYPE clause. The specification 
   of the optional MERGE_ATTRIBUTES and MERGE_PREFIX clauses results in the 
   copying of attributes from the ORIGINAL feature into the GML2 features. If 
   MERGE_PREFIX is used, then the string prefix is put at the start of each 
   attribute from the ORIGINAL feature. Since a GML2 document may contain 
   several features, the factory allows the sequence of GML2 features from a 
   particular GML2 document to be numbered; the optional FEATURE_NUMBER clause 
   can be used to specify the name of this attribute. Furthermore, each GML2 
   feature can also be tagged by a unique sequence number that identifies them 
   as coming from the same GML2 document; the optional FEATURE_ID clause can be 
   used to specify the name for this attribute. In case of an error in the GML2 
   document, if FAIL_IF_INVALID_GML is FALSE, no features will be extracted from 
   the GML2 document, and the input feature will be output via the 
   INVALID_GMLFEATURE_TYPE clause.

   The optional XFMAP clauses specifies the xfMaps document to used. If this is 
   not specified, then the GML2Factory assumes that the GML2 document contains 
   features stored with the GML2 SAFE schema.

   When the DIRECTION is WRITE, the factory constructs GML documents from the 
   input features and stores them in an attribute for the features that are 
   output by the OUTPUT GML2 FEATURE_TYPE clause; the attribute of the GML2 
   feature containing the GML2 document is specified by the GML2_ATTR_DATA 
   clause. The GML2 documents written under the attribute that is specified by 
   the GML2_ATTR_DATA clause conforms to the GML2 SAFE schema.

   At any given moment, the factory, whether it is being used in READ or WRITE 
   mode, is creating only one feature. The current feature being constructed is 
   output whenever any of the following is true:

      The values of any of the BREAK_BEFORE_FIELD_CHANGE fields change from one 
      feature to the next. When this occurs, the newly received input feature is 
      not part of the flushed feature, but rather is part of the next feature to 
      be constructed. Values of attributes named in these clauses are 
      transferred to the output features.

      The values of any of the BREAK_AFTER_FIELD_CHANGE fields change from one 
      feature to the next. When this occurs, the newly received input feature is 
      part of the flushed feature. Values of attributes named in these clauses 
      are transferred to the output features. 

Assumptions

   The features entering the factory in the READ direction are assumed to 
   contain an attribute that contains a valid GML2 document as its value; this 
   attribute must be identified by the GML_DATA_ATTR clause. If the GML2 
   document is invalid, the translation will fail unless FAIL_IF_INVALID_GML is 
   set to FALSE. 

   The output tag INVALID_GML, and the FAIL_IF_INVALID_GML field are only used 
   when the direction of the factory is set to READ.

Output Tags

   The GML2Factory supports the following output tags.
   
   ORIGINAL 
   
      The original, unchanged input features.

   GML2  
   
      The features extracted from the GML2 document in the READ direction, or 
      the features containing the GML2 document in the attribute specified by 
      the GML_DATA_ATTR in the WRITE direction. 

   INVALID_GML 
   
      The features that triggered an error when extracting features from a GML2 
      document. This is a subset of the features output via the ORIGINAL output 
      tag.

TO BE RESOLVED

   Added unimplemented END_CURRENT_WHEN and START_NEW_WHEN clauses to syntax, but not documented.