001package eu.cqse.check.framework.core;
002
003import java.io.Serializable;
004import java.util.List;
005import java.util.function.Function;
006
007import org.conqat.lib.commons.region.OffsetBasedRegion;
008
009import eu.cqse.check.CheckTextRegionLocation;
010import eu.cqse.check.framework.core.phase.ECodeViewOption.ETextViewOption;
011import eu.cqse.check.framework.core.phase.IExtractedValue;
012import eu.cqse.check.framework.core.phase.IGlobalExtractionPhase;
013import eu.cqse.check.framework.core.phase.ITokenElementContext;
014
015/**
016 * Context interface for custom checks, that provides custom check related
017 * functionality to a custom check.
018 * 
019 * Besides the token element access, this also provides methods for creation of
020 * findings and for accessing the results of global pre-computation phases.
021 */
022public interface ICheckContext extends ITokenElementContext {
023
024        /**
025         * Creates a finding with the given message for the whole analyzed token
026         * element.
027         */
028        public void createFindingForElement(String message) throws CheckException;
029
030        /**
031         * Creates a finding with the given message from the given start line
032         * (inclusive) to the given end line (inclusive). Provide the
033         * {@link ETextViewOption} that was used to get the token stream.
034         * 
035         * If textView is {@link ETextViewOption#UNFILTERED_CONTENT} and the finding
036         * refers to filtered code, then it will be ignored.
037         */
038        public void createFindingForLines(String message, int startLine, int endLine, ETextViewOption textView)
039                        throws CheckException;
040
041        /**
042         * Creates a finding for each entry in the given List of
043         * {@link OffsetBasedRegion} with the given message from the given start offsets
044         * (inclusive) to the corresponding end offsets (inclusive).
045         * 
046         * Offsets must be based on filtered content
047         * ({@link ETextViewOption#FILTERED_CONTENT}).
048         */
049        public void createFindingForSiblingsInCurrentFile(String message, List<OffsetBasedRegion> regions)
050                        throws CheckException;
051
052        /**
053         * Creates one finding for the given message and main location. Adds the given
054         * siblingLocations as siblings to the new finding.
055         * 
056         * The list of sibling locations must not contain the main location. All
057         * offsets/line numbers are based on {@link ETextViewOption#UNFILTERED_CONTENT}.
058         */
059        public void createFindingForSiblings(String message, CheckTextRegionLocation mainLocation,
060                        List<CheckTextRegionLocation> siblingLocations);
061
062        /**
063         * Creates a finding with the given message from the given start offset
064         * (inclusive) to the given end offset (inclusive). Provide the
065         * {@link ETextViewOption} that was used to get the token stream.
066         * 
067         * If textView is {@link ETextViewOption#UNFILTERED_CONTENT} and the finding
068         * refers to filtered code, then it will be ignored.
069         */
070        public void createFindingForOffsets(String message, int startOffset, int endOffset, ETextViewOption textView)
071                        throws CheckException;
072
073        /**
074         * Returns an accessor function to read results of the provided phase. The
075         * accessor returns the values for a given uniform path.
076         */
077        public <T extends IExtractedValue<D>, D extends Serializable> Function<String, List<T>> accessPhaseResult(
078                        Class<? extends IGlobalExtractionPhase<T, D>> phaseClass);
079
080        /**
081         * Returns an accessor function to read inverted results of the provided phase.
082         * The accessor returns the values for a given value.
083         */
084        public <T extends IExtractedValue<D>, D extends Serializable> Function<String, List<T>> accessPhaseInvertedResult(
085                        Class<? extends IGlobalExtractionPhase<T, D>> phaseClass);
086
087        /**
088         * Returns all values that have been extracted by the phase. This is potentially
089         * expensive if a lot of values are expected from a phase. For phases with few
090         * expected values, this can be used safely.
091         */
092        public <T extends IExtractedValue<D>, D extends Serializable> List<String> listAllPhaseValues(
093                        Class<? extends IGlobalExtractionPhase<T, D>> phaseClass);
094}