Syntax FACTORY_DEF ReferenceFactory [FACTORY_NAME ] [INPUT REFERENCER FEATURE_TYPE [ ]* []*]+ [INPUT REFERENCEE FEATURE_TYPE [ ]* []*]+ [GROUP_BY []+] [FLUSH_WHEN_GROUPS_CHANGE (Yes|No)] ( ( REFERENCEE_FIELDS []+ ( REFERENCER_FIELDS []+ | REFERENCER_FIELD_VAL ) ) | ( REFERENCE_TABLE [ ]+ ) | ( REFERENCE_TABLE [ (AUTO|NUM|STRING)]+ ) ) REFERENCE_INFO (ATTRIBUTES| GEOM_BUILD_POLYS| GEOM_BUILD_AGGREGATES| GEOM_BUILD_LINES_FROM_POINTS| GEOM_AND_ATTR_BUILD_POLYS| GEOM_AND_ATTR_BUILD_AGGREGATES| GEOM_AND_ATTR_BUILD_LINES_FROM_POINTS) [DIMENSION (USEFIRST|2|3)] [LIST_NAME ] [LIST_ATTRS_TO_INCLUDE []* ] [LIST_ATTRS_TO_INCLUDE_MODE (ALL|SELECTED)] [PROCESS_DUPLICATE_REFERENCEES [(YES|NO)]] [MERGE_ATTRIBUTES [(YES|NO)]] [MANAGE_FME_TYPE [(YES|NO)]] [BUILD_INCOMPLETE_REFERENCERS [(YES|NO)]] [DUPLICATE_ATTRIBUTES LIST] [DUPLICATE_ATTRIBUTES DELIMITED())] [ATTR_ACCUM_MODE (HANDLE_CONFLICT|PREFIX_SUPPLIER|SUPPLIER_ONLY)] [ATTR_CONFLICT_RES (REQUESTOR_IF_CONFLICT|SUPPLIER_IF_CONFLICT)] [IGNORE_NULLS [(YES|NO)]] [SUPPLIER_PREFIX ] [HANDLE_ARCS_ELLIPSES_AND_TEXT [(yes|no)]] [REJECT_INVALID_GEOM [(yes|no)]] [CLEANING_TOLERANCE (NONE|AUTO|)] [OUTPUT (COMPLETE|INCOMPLETE|REFERENCED|UNREFERENCED| NO_REFERENCES|NO_REFERENCEE_FIELD| DUPLICATE_REFERENCEE|REJECTED) FEATURE_TYPE [ ]* []*]* Overview Each ReferenceFactory accepts two kinds of features - Referencer and Referencee - and resolves references between them. The ReferenceFactory merges the geometry of the REFERENCEE features into REFERENCER features: the REFERENCERs look for information from the REFERENCEEs. For example, if you have a group of features that you want to combine with another group of features to get either their geometry or their attributes, or both, there is an attribute "key" value that each of them has that can be used to make the connection. REFERENCEEs are the features pointed to by a field of the REFERENCER features: When the REFERENCE_INFO directive is GEOMETRY_*, then the REFERENCEEs are the features that contain the geometry. Note The REFERENCER will lose its former geometry. When the REFERENCE_INFO directive is ATTRIBUTES, then the REFERENCEEs contain attribution that will be joined to the attribution of the REFERENCER features. Note Any fme_* attributes present on the REFERENCEE features will not be transferred to the REFERENCER feature. When the REFERENCE_INFO directive is GEOM_AND_ATTR_*, then the REFERENCEEs contain both geometry and attribution that will be joined to the REFERENCER features. Any geometry on the REFERENCER will be overwritten. Attributes on the REFERENCER may or may not be overwritten, depending on whether any DUPLICATE_ATTRIBUTES or LIST_NAME clause is given. All features processed by the ReferenceFactory must share the same dimension. If DIMENSION is set to USEFIRST, then the dimension of the first feature going into the ReferenceFactory will be used to set the dimension of all features that follow. If DIMENSION is set to 2 or 3, then all features processed by the ReferenceFactory will have their features set to 2 or 3 respectively. The default setting is USEFIRST. The input features may be partitioned by the GROUP_BY clause. If the GROUP_BY clause is specified, then references between features will only be resolved if they share a common value for the GROUP_BY attributes. If FLUSH_WHEN_GROUPS_CHANGE is set to Yes, references between features currently in the factory will be resolved immediately upon encountering a feature from a different group, flushing the current group. If no GROUP_BY clause is specified, all features are processed together. A typical use is to GROUP_BY multi_reader_id when features are coming from a multi-reader to ensure that references are resolved within the correct set of features. The factory performs the following operations: All REFERENCEE features for each REFERENCER feature are identified. The geometry from the identified REFERENCEE features is then combined to form the geometry of the REFERENCER feature. If REFERENCE_INFO is *_BUILD_AGGREGATES, the ReferenceFactory will create an aggregate of the geometries of the REFERENCEE features. (If there is only one REFERENCEE feature, then the REFERENCER geometry will be an aggregate with one element.) If REFERENCE_INFO is *_BUILD_POLYS, and the REFERENCEEs consist exclusively of polygon and donut polygon features, then any common border segments will be removed. If REFERENCE_INFO is *_BUILD_POLYS and the REFERENCEEs contain at least one donut or polygon feature, then the ReferenceFactory will form polygons and donuts from the REFERENCEEs, and will join connected line segments of the REFERENCEE features before setting the geometry of the REFERENCER feature. In this last situation, the geometry may be an aggregate if several disjoint geometries were created. Lastly, if REFERENCE_INFO is *_BUILD_LINES_FROM_POINTS, the ReferenceFactory will connect the points of the REFERENCEES features into lines. Any non-point features that are referenced will be ignored when building lines. The attributes from the identified REFERENCEE features are then combined to form the attributes of the REFERENCER feature. See the details for the DUPLICATE_ATTRIBUTES and LIST_NAME clauses below for more information. REFERENCEE features referenced are output by the output tag REFERENCED. REFERENCEE features not referenced by any REFERENCER feature are output by the output tag UNREFERENCED. REFERENCER features matched with all features they reference are output by the output tag COMPLETE. REFERENCER features that refer to one or more REFERENCEE features not found are output by the output tag INCOMPLETE. If BUILD_INCOMPLETE_REFERENCERS is specified, these features will have been merged with any that were actually found; otherwise, they will be untouched and any partial matches will be output as UNREFERENCED. REFERENCEE features that do not have any attributes identified by the REFERENCEE_FIELDS clause are output by the tag NO_REFERENCEE_FIELD. REFERENCEE features with the same value for the REFERENCEE_FIELDS as a previously encountered REFERENCEE are output via the DUPLICATE_REFERENCEE tag. REFERENCER features that do not have any value for the REFERENCER_FIELDS are output by the NO_REFERENCES tag. Additional statistical information about the operation of the ReferenceFactory may be output by specifying FME_DEBUG ReferenceFactory in the mapping file. For details, search Mapping File Debugging in FME Fundamentals help. At the completion of the run the number of features which fall into each group are reported to the logfile. The factory makes no assumptions on the order in which features arrive to the factory. Ideally, all the TARGET_FEATURES would arrive first but realistically this cannot be assumed. If REJECT_INVALID_GEOM is yes, then features that need to be rejected will be rejected. Input Tags The ReferenceFactory supports the following input tags. REFERENCEE Features pointed to by one or more referencers. REFERENCER Features that point to one or more referencees. Clauses The ReferenceFactory supports several configuration clauses. REFERENCEE_FIELDS []+ defines the fields that make up the REFERENCEE key. If multiple fields are specified, then the key will be the concatenation of the fields in the order in which the name is specified. List attribute names may not be specified as part of the REFERENCEE_FIELDS. REFERENCER_FIELDS []+ defines the fields within the REFERENCER object which, when combined, refer to a REFERENCEE object. If multiple keys are specified, then the key values are concatenated in the order specified on the clause. The ReferenceFactory uses the resulting key to find the REFERENCEE object. If a list attribute is specified for REFERENCER_FIELDS, then each of the list entries is used as a separate key to reference multiple REFERENCEE objects. If a list attribute is specified, no other fields can be specified. List attributes must contain a {} pair. REFERENCER_FIELD_VAL - only specify either REFERENCER_FIELDS or REFERENCER_FIELD_VAL. Use REFERENCER_FIELD_VAL when you want an evaluated expression as the referencer key. Unlike REFERENCER_FIELDS this is a single expression (since the user can concatenate themselves in the expression). REFERENCE_TABLE - a pairing of requestor/supplier keys to join on where each pair is an expression. Only one of REFERENCER_FIELD_VAL, REFERENCER_FIELDS or REFERENCEE_FIELDS should be input. Also if table is used REMOVE_REF_ATTR is ignored REFERENCE_TABLE_EX - like REFERENCE_TABLE, but each pair is followed by AUTO, NUM, or STRING to dictate how the comparison should be made between those values. If either LIST_NAME or PROCESS_DUPLICATE_REFERENCEES is given, then any number of REFERENCEE features will be allowed per REFERENCER. In the case of LIST_NAME, if attributes are to be combined, then all attributes of each REFERENCEE will be added to any REFERENCER that it matches, prefixed by "{index}." (index is zero for the first matching REFERENCEE, one for the second, and so on.) So if the third REFERENCEE for a given REFERENCER has an attribute named myattr, and LIST_NAME mylist was specified, then mylist{2}.myattr will be added to the REFERENCER. The optional LIST_ATTRS_TO_INCLUDE_MODE will specify if ALL attributes should be added to a list, or if only the SELECTED attributes (specified with the LIST_ATTRS_TO_INCLUDE clause) should be added to the list. If this value is not specified, it defaults to ALL. If PROCESS_DUPLICATE_REFERENCEES is set to NO, it means that any REFERENCEE features that have the same REFERENCEE_FIELDS are output using the DUPLICATE_REFERENCEE output. Only the first of the REFERENCEES will be matched with a REFERENCER. If set to YES, then the duplicate REFERENCEES are all matched with the corresponding REFERENCER. When REFERENCE_INFO is set to ATTRIBUTES or GEOM_AND_ATTR_*, this factory merges attributes between referencer/referencee features. The merging is based on these parameters: ATTR_ACCUM_MODE, ATTR_CONFLICT_RES, IGNORE_NULLS and SUPPLIER_PREFIX. The merging may take the original or incoming attributes, possibly prefixed, based on the combinations of these various parameters. If MERGE_ATTRIBUTES is specified, when ATTR_ACCUM_MODE is set to DEFAULT_MERGEMODE, then existing attributes on a REFERENCER feature will never be overwritten by attributes of the same name on any REFERENCEE features. When MANAGE_FME_TYPE is given, the factory will assign the appropriate value to the fme_type attribute on those features whose geometry is changed, according to the resultant geometry. Otherwise, fme_type remains unaltered. The BUILD_INCOMPLETE_REFERENCERS clause specifies the factory's behavior for REFERENCERs that fail to find a match with all their (multiple) REFERENCEEs. If the clause is YES, any REFERENCEES that do match are merged onto the REFERENCER and the REFERENCEE is output via the REFERENCED tag. The partially built REFERENCER is then output via the INCOMPLETE tag of the factory. If the clause is NO, any REFERENCEES that are part of an incomplete referencer are output as UNREFERENCED and the REFERENCER is left untouched. The REFERENCER is again output as INCOMPLETE. When the clause is NO the only way that a REFERENCEE is output as REFERENCED is if it is referenced by a REFERENCER that is complete. The DUPLICATE_ATTRIBUTES clause directs the ReferenceFactory how to handle duplicate attributes when a referencer points to multiple referencees, due to the referencer key field being a list attribute. If not specified, then the attribute values of the last REFERENCEE are kept. If the value of the DUPLICATE_ATTRIBUTES clause is LIST, then the attributes that occur in multiple REFERENCEEs are stored in a list attribute of the form {0}, {1} etc. If the value of the DUPLICATE_ATTRIBUTES clause is DELIMITED(), then the attribute's values are stored in a single attribute named with the multiple entries separated by . is a string of 1 or more characters. Common values for are one of " | , # ! " and space. Note: You cannot have more than one REFERENCEE feature with the same key, assuming neither LIST_NAME nor PROCESS_DUPLICATE_REFERENCEES is specified. The DUPLICATE_ATTRIBUTES clauses are used if the REFERENCER has a list for the REFERENCER_FIELD. This way, there can be more than one REFERENCEE feature matched to one REFERENCER feature. To match more than one REFERENCER feature, you could use the ListFactory first, to group together REFERENCEE features. If the CLEANING_TOLERANCE keyword does not exist or has the value "NONE", no cleaning will be performed. If the CLEANING_TOLERANCE directive specifies a non-negative number, geometries within this tolerance will be merged. If the CLEANING_TOLERANCE is AUTO, a cleaning tolerance will be automatically generated based on the input geometries. Output Tags Features which belong to an OUTPUT TAG not specified are deleted by the factory. If the tag is specified then the features are unchanged except new attributes can be added to the feature. The ReferenceFactory supports the following output tags. COMPLETE REFERENCER features for which all referenced features were present. COMPLETE source features are released from the Factory as soon as they are completed. INCOMPLETE REFERENCER features for which one or more referenced features were missing. REFERENCED REFERENCEE features referenced by one or more REFERENCER features. UNREFERENCED REFERENCEE features not referenced by any feature. NO_REFERENCES REFERENCER features that do not have any value for the REFERENCER_FIELD attribute. DUPLICATE_REFERENCEE REFERENCEE features with the same value for the REFERENCEE_FIELDS attributes. Note: No DUPLICATE_REFERENCEEs will be output if LIST_NAME or PROCESS_DUPLICATE_REFERENCEES is specified. NO_REFERENCEE_FIELD REFERENCEE features with no value for the REFERENCEE_FIELDS attributes. REJECTED Rejected features are outputted to this port. TO BE RESOLVED HANDLE_ARCS_ELLIPSES_AND_TEXT clause added to Syntax section above, but not documented. This clause is now deprecated, but kept for legacy purposes.