001/*
002 * To change this template, choose Tools | Templates
003 * and open the template in the editor.
004 */
005
006package ca.uhn.hl7v2.model;
007
008import ca.uhn.hl7v2.HL7Exception;
009import ca.uhn.hl7v2.Location;
010
011/**
012 * A MessageVisitor can be used to traverse a message structure. Everytime a
013 * message element is found, the corresponding visitable method is called. If
014 * a method returns <code>true</code>, the visiting process is continued,
015 * otherwise abandoned.
016 * <p>
017 * A MessageVisitor should usually only be called by
018 * {@link Visitable#accept(MessageVisitor, Location)}.
019 * </p>
020 */
021public interface MessageVisitor {
022
023    /**
024     * Enters a message
025     * @param message message
026     * @return true if the visitor shall descend into the nested structures
027     * @throws HL7Exception if an error occurred while visiting
028     */    
029    public boolean start(Message message) throws HL7Exception;
030
031    /**
032     * Leaves a message
033     * @param message message
034     * @return true if the visitor shall descend into the nested structures
035     * @throws HL7Exception if an error occurred while visiting
036     */
037    public boolean end(Message message) throws HL7Exception;
038
039    /**
040     * Enters a group (or message)
041     * @param group group
042     * @param location Location object describing the location within the message
043     * @return true if the visitor shall descend into the nested structures
044     * @throws HL7Exception if an error occurred while visiting
045     */
046    boolean start(Group group, Location location) throws HL7Exception;
047
048    /**
049     * Leaves a group (or message)
050     * @param group group
051     * @param location Location object describing the location within the message
052     * @return true if the visitor shall continue visiting the parent structure
053     * @throws HL7Exception if an error occurred while visiting
054     */
055    boolean end(Group group, Location location) throws HL7Exception;
056
057    /**
058     * Enters a segment
059     * @param segment segment
060     * @param location Location object describing the location within the message
061     * @return true if the visitor shall descend into the nested structures
062     * @throws HL7Exception if an error occurred while visiting
063     */
064    boolean start(Segment segment, Location location) throws HL7Exception;
065
066    /**
067     * Leaves a segment
068     * @param segment segment
069     * @param location Location object describing the location within the message
070     * @return true if the visitor shall continue visiting the parent structure
071     * @throws HL7Exception if an error occurred while visiting
072     */
073    boolean end(Segment segment, Location location) throws HL7Exception;
074
075    /**
076     * Enters a field. Note that a field is *not* a physical part of the HAPI
077     * model class hierarchy; it merely encapsulates all repetitions of a specific
078     * field along with its substructures.
079     * 
080     * @param field field
081     * @param location Location object describing the location within the message
082     * @return true if the visitor shall descend into the nested structures
083     * @throws HL7Exception if an error occurred while visiting
084     */
085    boolean start(Field field, Location location) throws HL7Exception;
086
087    /**
088     * Leaves a field. Note that a field is *not* a physical part of the HAPI
089     * model class hierarchy; it merely encapsulates all repetitions of a specific
090     * field along with its substructures.
091     * 
092     * @param field field
093     * @param location Location object describing the location within the message
094     * @return true if the visitor shall continue visiting the parent structure
095     * @throws HL7Exception if an error occurred while visiting
096     */
097    boolean end(Field field, Location location) throws HL7Exception;
098    
099    /**
100     * Enters a composite
101     * @param type composite
102     * @param location Location object describing the location within the message
103     * @return true if the visitor shall descend into the nested structures
104     * @throws HL7Exception if an error occurred while visiting
105     */
106    boolean start(Composite type, Location location) throws HL7Exception;
107
108    /**
109     * Leaves a composite
110     * @param type composite
111     * @param location Location object describing the location within the message
112     * @return true if the visitor shall continue visiting the parent structure
113     * @throws HL7Exception if an error occurred while visiting
114     */
115    boolean end(Composite type, Location location) throws HL7Exception;
116
117    /**
118     * Visits a primitive
119     * @param type primitive
120     * @param location Location object describing the location within the message
121     * @return true if the visitor shall descend into the nested structures
122     * @throws HL7Exception if an error occurred while visiting
123     */
124    boolean visit(Primitive type, Location location) throws HL7Exception;
125
126}