xdev.util.systemproperty.SystemProperty Maven / Gradle / Ivy

Go to download
/*
 * XDEV Application Framework - XDEV Application Framework
 * Copyright © 2003 XDEV Software (https://xdev.software)
 *
 * This program 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 3 of the License, or
 * (at your option) any later version.
 *
 * This program 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 program.  If not, see .
 */
package xdev.util.systemproperty;


import xdev.lang.Nullable;


/**
 * 
 * {@link SystemProperty} is a thin wrapper around the java system properties
 * facility. It provides type-safe access to a system property and is aware of
 * the name of that property.
 * 
 * 
 * @author XDEV Software (RHHF)
 * @since 3.2
 * 
 * @param 
 *            type of the {@link SystemProperty} that is wrapped.
 */
public interface SystemProperty
{
	
	/**
	 * Determines the value of the system property specified by
	 * {@link #getName()}.
	 * 
	 * 
	 * 
	 * @return the value of the property. null if the specified
	 *         system property was not found or the value could not be parsed.
	 */
	public @Nullable
	T getValue();
	

	/**
	 * Determines the value of the system property specified by
	 * {@link #getName()}.
	 * 
	 * @param defaultValue
	 *            will be returned if the specified system property was not
	 *            found.
	 * 
	 * @return the value of the property. defaultValue if the
	 *         specified system property was not found or the value could not be
	 *         parsed.
	 */
	public @Nullable
	T getValue(final @Nullable T defaultValue);
	

	/**
	 * Returns the name of the system property that is wrapped by this
	 * {@link SystemProperty} instance.
	 * 
	 * @return the name of the system property that is wrapped by this
	 *         {@link SystemProperty} instance.
	 */
	public @Nullable
	String getName();
	

	/**
	 * Sets the system property specified by {@link #getName()}.
	 * 
	 * First, if a security manager exists, its
	 * SecurityManager.checkPermission method is called with a
	 * PropertyPermission(key, "write") permission. This may result
	 * in a SecurityException being thrown. If no exception is thrown, the
	 * specified property is set to the given value.
	 * 
	 * 
	 * 
	 * @param value
	 *            the value of the system property.
	 * @return the previous value of the system property, or null
	 *         if it did not have one.
	 * 
	 * @exception SecurityException
	 *                if a security manager exists and its
	 *                checkPermission method doesn't allow setting
	 *                of the specified property.
	 * @exception NullPointerException
	 *                if {@link #getName()} or value
	 *                is null.
	 * @exception IllegalArgumentException
	 *                if {@link #getName()} is empty.
	 */
	public @Nullable
	String setValue(final @Nullable T value) throws SecurityException, NullPointerException,
			IllegalArgumentException;
	

	/**
	 * Removes the system property from the system property set.
	 */
	public void clear();
	
}