INullnessAnnotationDatabase.java

/*
 * FindBugs - Find Bugs in Java programs
 * Copyright (C) 2003-2007 University of Maryland
 *
 * This library is free software; you can redistribute it and/or
 * modify it under the terms of the GNU Lesser General Public
 * License as published by the Free Software Foundation; either
 * version 2.1 of the License, or (at your option) any later version.
 *
 * This library is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 * Lesser General Public License for more details.
 *
 * You should have received a copy of the GNU Lesser General Public
 * License along with this library; if not, write to the Free Software
 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
 */

package edu.umd.cs.findbugs.ba;

import javax.annotation.CheckForNull;

import edu.umd.cs.findbugs.internalAnnotations.DottedClassName;

/**
 * Interface for querying nullness annotations on methods, fields, and
 * parameters.
 * 
 * @author David Hovemeyer
 */
public interface INullnessAnnotationDatabase {

    /**
     * Determine whether given parameter must be non-null.
     * 
     * @param m
     *            a method
     * @param param
     *            parameter (0 == first parameter)
     * @return true if the parameter must be non-null, false otherwise
     */
    public abstract boolean parameterMustBeNonNull(XMethod m, int param);

    /**
     * Get a resolved NullnessAnnotation on given XMethod, XField, or
     * XMethodParameter.
     * 
     * @param o
     *            an XMethod, XField, or XMethodParameter
     * @param getMinimal
     *            TODO: what does this mean?
     * @return resolved NullnessAnnotation
     */
    @CheckForNull
    public abstract NullnessAnnotation getResolvedAnnotation(final Object o, boolean getMinimal);

    /**
     * Load "built-in" annotations that might not be evident from the
     * analyzed/referenced code.
     */
    public void loadAuxiliaryAnnotations();

    // /**
    // * Add a default nullness annotation to the database.
    // *
    // * @param cName class name (FIXME: is this right?)
    // * @param annotation the default NullnessAnnotation
    // */
    // public void addDefaultMethodAnnotation(String cName, NullnessAnnotation
    // annotation);

    /**
     * Add a field annotation to the database.
     * 
     * @param cName
     *            dotted class name
     * @param mName
     *            field name
     * @param mSig
     *            field signature
     * @param isStatic
     *            true if field is static, false otherwise
     * @param annotation
     *            NullnessAnnotation to add
     */
    public void addFieldAnnotation(@DottedClassName String cName, String mName, String mSig, boolean isStatic,
            NullnessAnnotation annotation);

    /**
     * Add a method annotation to the database.
     * 
     * @param cName
     *            dotted class name
     * @param mName
     *            method name
     * @param mSig
     *            method signature
     * @param isStatic
     *            true if method is static, false otherwise
     * @param annotation
     *            NullnessAnnotation to add
     */
    public void addMethodAnnotation(@DottedClassName String cName, String mName, String mSig, boolean isStatic,
            NullnessAnnotation annotation);

    /**
     * Add a method parameter annotation to the database.
     * 
     * @param cName
     *            dotted class name
     * @param mName
     *            method name
     * @param mSig
     *            method signature
     * @param isStatic
     *            true if method is static, false otherwise
     * @param param
     *            parameter (0 == first parameter)
     * @param annotation
     *            the NullnessAnnotation to add
     */
    public void addMethodParameterAnnotation(@DottedClassName String cName, String mName, String mSig, boolean isStatic,
            int param, NullnessAnnotation annotation);

    /**
     * Add a default annotation to the database.
     * 
     * @param target
     *            one of AnnotationDatabase.METHOD, AnnotationDatabase.FIELD,
     *            AnnotationDatabase.PARAMETER, or AnnotationDatabase.ANY
     * @param c
     *            dotted class name of class default annotation pertains to
     * @param n
     *            the default NullnessAnnotation
     */
    public void addDefaultAnnotation(AnnotationDatabase.Target target, @DottedClassName String c, NullnessAnnotation n);
}