buginstance.java

A static analysis tool to find bugs in Java programs

	 *  [barring an intervening setUserDesignation(null)].
	 *  @see #getNonnullUserDesignation() */
	@Nullable public BugDesignation getUserDesignation() {
		return userDesignation;
	}
	/** return the user designation object, creating one if
	 *  necessary. So calling
	 *  <code>getSafeUserDesignation().setDesignation("HARMLESS")</code>
	 *  will always work without the possibility of a NullPointerException.
	 *  @see #getUserDesignation() */
	@NonNull public BugDesignation getNonnullUserDesignation() {
		if (userDesignation == null)
			userDesignation = new BugDesignation();
		return userDesignation;
	}


	/** Get the user designation key.
	 *  E.g., "MOSTLY_HARMLESS", "CRITICAL", "NOT_A_BUG", etc.
	 *
	 *  If the user designation object is null,returns UNCLASSIFIED.
	 *
	 *  To set the user designation key, call
	 *  <code>getSafeUserDesignation().setDesignation("HARMLESS")</code>.
	 * 
	 *  @see I18N#getUserDesignation(String key)
	 *  @return the user designation key
	 */
	@NonNull public String getUserDesignationKey() {
		BugDesignation userDesignation = this.userDesignation;
		if (userDesignation == null) return BugDesignation.UNCLASSIFIED;
		return userDesignation.getDesignationKey();
	}

	/**
	 * Set the user annotation text.
	 *
	 * @param annotationText the user annotation text
	 */
	public void setAnnotationText(String annotationText) {
		getNonnullUserDesignation().setAnnotationText(annotationText);
	}

	/**
	 * Get the user annotation text.
	 *
	 * @return the user annotation text
	 */
	@NonNull public String getAnnotationText() {
		BugDesignation userDesignation = this.userDesignation;
		if (userDesignation == null) return "";		
		String s = userDesignation.getAnnotationText();
		if (s == null) return "";
		return s;
	}

	/**
	 * Determine whether or not the annotation text contains
	 * the given word.
	 *
	 * @param word the word
	 * @return true if the annotation text contains the word, false otherwise
	 */
	public boolean annotationTextContainsWord(String word) {
		return getTextAnnotationWords().contains(word);
	}

	/**
	 * Get set of words in the text annotation.
	 */
	public Set<String> getTextAnnotationWords() {
		HashSet<String> result = new HashSet<String>();

		StringTokenizer tok = new StringTokenizer(getAnnotationText(), " \t\r\n\f.,:;-");
		while (tok.hasMoreTokens()) {
			result.add(tok.nextToken());
		}
		return result;
	}

	/**
	 * Get the BugInstance's unique id.
	 * 
	 * @return the unique id, or null if no unique id has been assigned
	 * 
	 * Deprecated, since it isn't persistent
	 */
	@Deprecated
	public String getUniqueId() {
		return uniqueId;
	}

	/**
	 * Set the unique id of the BugInstance.
	 * 
	 * @param uniqueId the unique id
	 * 
	 *   * Deprecated, since it isn't persistent
	 */
	@Deprecated
	 void setUniqueId(String uniqueId) {
		this.uniqueId = uniqueId;
	}



	/* ----------------------------------------------------------------------
	 * Property accessors
	 * ---------------------------------------------------------------------- */

	private class BugPropertyIterator implements Iterator<BugProperty> {
		private BugProperty prev, cur;
		private boolean removed;

		/* (non-Javadoc)
		 * @see java.util.Iterator#hasNext()
		 */
		public boolean hasNext() {
			return findNext() != null;
		}
		/* (non-Javadoc)
		 * @see java.util.Iterator#next()
		 */
		public BugProperty next() {
			BugProperty next = findNext();
			if (next == null)
				throw new NoSuchElementException();
			prev = cur;
			cur = next;
			removed = false;
			return cur;
		}

		/* (non-Javadoc)
		 * @see java.util.Iterator#remove()
		 */
		public void remove() {
			if (cur == null || removed)
				throw new IllegalStateException();
			if (prev == null) {
				propertyListHead = cur.getNext();
			} else {
				prev.setNext(cur.getNext());
			}
			if (cur == propertyListTail) {
				propertyListTail = prev;
			}
			removed = true;
		}

		private BugProperty findNext() {
			return cur == null ? propertyListHead : cur.getNext();
		}

	}

	/**
	 * Get value of given property.
	 * 
	 * @param name name of the property to get
	 * @return the value of the named property, or null if
	 *         the property has not been set
	 */
	public String getProperty(String name) {
		BugProperty prop = lookupProperty(name);
		return prop != null ? prop.getValue() : null;
	}

	/**
	 * Get value of given property, returning given default
	 * value if the property has not been set.
	 * 
	 * @param name         name of the property to get
	 * @param defaultValue default value to return if propery is not set
	 * @return the value of the named property, or the default
	 *         value if the property has not been set
	 */
	public String getProperty(String name, String defaultValue) {
		String value = getProperty(name);
		return value != null ? value : defaultValue;
	}

	/**
	 * Get an Iterator over the properties defined in this BugInstance.
	 * 
	 * @return Iterator over properties
	 */
	public Iterator<BugProperty> propertyIterator() {
		return new BugPropertyIterator();
	}

	/**
	 * Set value of given property.
	 * 
	 * @param name  name of the property to set
	 * @param value the value of the property
	 * @return this object, so calls can be chained
	 */
	public BugInstance setProperty(String name, String value) {
		BugProperty prop = lookupProperty(name);
		if (prop != null) {
			prop.setValue(value);
		} else {
			prop = new BugProperty(name, value);
			addProperty(prop);
		}
		return this;
	}

	/**
	 * Look up a property by name.
	 * 
	 * @param name name of the property to look for
	 * @return the BugProperty with the given name,
	 *         or null if the property has not been set
	 */
	public BugProperty lookupProperty(String name) {
		BugProperty prop = propertyListHead;

		while (prop != null) {
			if (prop.getName().equals(name))
				break;
			prop = prop.getNext();
		}

		return prop;
	}

	/**
	 * Delete property with given name.
	 * 
	 * @param name name of the property to delete
	 * @return true if a property with that name was deleted,
	 *         or false if there is no such property
	 */
	public boolean deleteProperty(String name) {
		BugProperty prev = null;
		BugProperty prop = propertyListHead;

		while (prop != null) {
			if (prop.getName().equals(name))
				break;
			prev = prop;
			prop = prop.getNext();
		}

		if (prop != null) {
			if (prev != null) {
				// Deleted node in interior or at tail of list
				prev.setNext(prop.getNext());
			} else {
				// Deleted node at head of list
				propertyListHead = prop.getNext();
			}

			if (prop.getNext() == null) {
				// Deleted node at end of list
				propertyListTail = prev;
			}

			return true;
		} else {
			// No such property
			return false;
		}
	}

	private void addProperty(BugProperty prop) {
		if (propertyListTail != null) {
			propertyListTail.setNext(prop);
			propertyListTail = prop;
		} else {
			propertyListHead = propertyListTail = prop;
		}
		prop.setNext(null);
	}

	/* ----------------------------------------------------------------------
	 * Generic BugAnnotation adders
	 * ---------------------------------------------------------------------- */

	/**
	 * Add a Collection of BugAnnotations.
	 * 
	 * @param annotationCollection Collection of BugAnnotations
	 */
	public BugInstance addAnnotations(Collection<? extends BugAnnotation> annotationCollection) {
		for (BugAnnotation annotation : annotationCollection) {
			add(annotation);
		}
		return this;
	}

	/* ----------------------------------------------------------------------
	 * Combined annotation adders
	 * ---------------------------------------------------------------------- */

	public BugInstance addClassAndMethod(MethodDescriptor methodDescriptor) {
		addClass(methodDescriptor.getClassName());
		add(MethodAnnotation.fromMethodDescriptor(methodDescriptor));
		return this;
	}

	/**
	 * Add a class annotation and a method annotation for the class and method
	 * which the given visitor is currently visiting.
	 *
	 * @param visitor the BetterVisitor
	 * @return this object
	 */
	public BugInstance addClassAndMethod(PreorderVisitor visitor) {
		addClass(visitor);
		addMethod(visitor);
		return this;
	}

	/**
	 * Add class and method annotations for given method.
	 *
	 * @param methodAnnotation  the method
	 * @return this object
	 */
	public BugInstance addClassAndMethod(MethodAnnotation methodAnnotation) {
		addClass(methodAnnotation.getClassName());
		addMethod(methodAnnotation);
		return this;
	}

	/**
	 * Add class and method annotations for given method.
	 *
	 * @param methodGen  the method
	 * @param sourceFile source file the method is defined in
	 * @return this object
	 */
	public BugInstance addClassAndMethod(MethodGen methodGen, String sourceFile) {
		addClass(methodGen.getClassName());
		addMethod(methodGen, sourceFile);
		return this;
	}


	/**
	 * Add class and method annotations for given class and method.
	 *  
	 * @param javaClass the class
	 * @param method    the method
	 * @return this object
	 */
	public BugInstance addClassAndMethod(JavaClass javaClass, Method method) {
		addClass(javaClass.getClassName());
		addMethod(javaClass, method);
		return this;
	}

	/* ----------------------------------------------------------------------
	 * Class annotation adders
	 * ---------------------------------------------------------------------- */

	/**
	 * Add a class annotation.  If this is the first class annotation added,
	 * it becomes the primary class annotation.
	 *
	 * @param className the name of the class
	 * @param sourceFileName the source file of the class
	 * @return this object
	 * @deprecated use addClass(String) instead
	 */
	public BugInstance addClass(String className, String sourceFileName) {
		ClassAnnotation classAnnotation = new ClassAnnotation(className);
		add(classAnnotation);
		return this;
	}

	/**
	 * Add a class annotation.  If this is the first class annotation added,
	 * it becomes the primary class annotation.
	 *
	 * @param className the name of the class
	 * @return this object
	 */
	public BugInstance addClass(String className) {
		className = ClassName.toDottedClassName(className);
		ClassAnnotation classAnnotation = new ClassAnnotation(className);
		add(classAnnotation);
		return this;
	}

	/**
	 * Add a class annotation for the classNode.
	 *
	 * @param classNode the ASM visitor
	 * @return this object
	 */
	public BugInstance addClass(ClassNode classNode) {
		ClassAnnotation classAnnotation = new ClassAnnotation(classNode.name);
		add(classAnnotation);
		return this;
	}

	/**
	 * Add a class annotation.  If this is the first class annotation added,
	 * it becomes the primary class annotation.
	 * 
	 * @param classDescriptor the class to add
	 * @return this object
	 */
	public BugInstance addClass(ClassDescriptor classDescriptor) {
		add(ClassAnnotation.fromClassDescriptor(classDescriptor));
		return this;
	}

	/**
	 * Add a class annotation.  If this is the first class annotation added,
	 * it becomes the primary class annotation.
	 *
	 * @param jclass the JavaClass object for the class
	 * @return this object
	 */
	public BugInstance addClass(JavaClass jclass) {
		addClass(jclass.getClassName());
		return this;
	}

	/**
	 * Add a class annotation for the class that the visitor is currently visiting.
	 *
	 * @param visitor the BetterVisitor
	 * @return this object
	 */
	public BugInstance addClass(PreorderVisitor visitor) {
		String className = visitor.getDottedClassName();
		addClass(className);
		return this;
	}

	/**
	 * Add a class annotation for the superclass of the class the visitor
	 * is currently visiting.
	 *
	 * @param visitor the BetterVisitor
	 * @return this object
	 */
	public BugInstance addSuperclass(PreorderVisitor visitor) {
		String className = visitor.getSuperclassName();
		addClass(className);
		return this;
	}

	/* ----------------------------------------------------------------------
	 * Type annotation adders
	 * ---------------------------------------------------------------------- */

	/**
	 * Add a type annotation. Handy for referring to array types.
	 *
	 * <p>For information on type descriptors,
	 * <br>see http://java.sun.com/docs/books/vmspec/2nd-edition/html/ClassFile.doc.html#14152
	 * <br>or  http://www.murrayc.com/learning/java/java_classfileformat.shtml#TypeDescriptors
	 * 
	 * @param typeDescriptor a jvm type descriptor, such as "[I"
	 * @return this object
	 */
	public BugInstance addType(String typeDescriptor) {
		TypeAnnotation typeAnnotation = new TypeAnnotation(typeDescriptor);
		add(typeAnnotation);
		return this;