• Home
• de.uni.freiburg.iig.telematik
• SEPIA
• 1.0.2
• source code
• AbstractPlace.java

×

Project download

Many resources are needed to download a project. Please understand that we have to compensate our server costs. Thank you in advance.
Project price only 1 $

You can buy this project and download/modify it how often you want.

de.uni.freiburg.iig.telematik.sepia.petrinet.abstr.AbstractPlace Maven / Gradle / Ivy

package de.uni.freiburg.iig.telematik.sepia.petrinet.abstr;

import java.io.Serializable;
import java.util.List;

import de.invation.code.toval.validate.ParameterException;
import de.invation.code.toval.validate.Validate;
import de.uni.freiburg.iig.telematik.sepia.event.CapacityEvent;
import de.uni.freiburg.iig.telematik.sepia.event.PlaceListener;
import de.uni.freiburg.iig.telematik.sepia.event.PlaceListenerSupport;
import de.uni.freiburg.iig.telematik.sepia.event.TokenListener;
import de.uni.freiburg.iig.telematik.sepia.event.TokenListenerSupport;
import de.uni.freiburg.iig.telematik.sepia.exception.PNValidationException;

/**
 * Abstract class that defines general properties for Petri net places.

 * This class inherits basic Petri net node properties from {@link AbstractPNNode}

 * and defines additional properties:

 * 

 * 
Capacity: The maximum number of tokens that can reside in the place.

 * A capacity of -1 is interpreted as unboundedness, i.e. the number and kind of tokens is not restricted.
 * 
 * 

 * A place maintains a state of type S, which defines the number and kind of tokens in the place.

 * The type S is used for the internal state of the place and for adding and removing tokens from the place. A place allows {@link TokenListener}s to register so that they can be notified on state changes,

 * i.e. added/removed tokens.
 * 
 * @author Thomas Stocker
 * 
 * @param 
 *            The type of flow relations connected to the place.
 * @param 
 *            Type for token number and type.
 */
public abstract class AbstractPlace, 
									? extends AbstractTransition, S>, 
									S extends Object> 
									extends AbstractPNNode implements Serializable{

	private static final long serialVersionUID = -4942014250666222432L;
	
	/**
	 * Support class for {@link TokenListener} handling.
	 */
	protected TokenListenerSupport> tokenListenerSupport = new TokenListenerSupport>();
	/**
	 * Support class for {@link PlaceListener} handling.
	 */
	protected PlaceListenerSupport> placeListenerSupport = new PlaceListenerSupport>();
	/**
	 * Capacity of the place, i.e. the maximum number of tokens the place can hold.

	 * A capacity of -1 is interpreted as unboundedness, i.e. the number and kind of tokens is not restricted.
	 */
	protected int capacity = -1;
	/**
	 * The state of the place, i.e. the number and kind of tokens that reside in the place.
	 */
	protected S state = null;

	// ------- Constructors --------------------------------------------------------------------------

//	protected AbstractPlace() {
//		super(PNNodeType.PLACE);
//	}

	/**
	 * Creates a new place with the given name.
	 * @param name The name for the new Place.
	 * @throws ParameterException If the given name is null.
	 */
	public AbstractPlace(String name){
		super(PNNodeType.PLACE, name);
	}

	/**
	 * Creates a new place with the given name and label.
	 * 
	 * @param name
	 *            The name for the new place.
	 * @param label
	 *            The label for the new place.
	 */
	public AbstractPlace(String name, String label){
		super(PNNodeType.PLACE, name, label);
	}

	// ------- Basic properties -----------------------------------------------------------------------

	/**
	 * Returns the capacity of the place, i.e.

	 * the maximum number of tokens the place can hold.
	 * 
	 * @return The capacity of the place.
	 */
	public int getCapacity() {
		return capacity;
	}

	/**
	 * Sets the capacity of the place, i.e.

	 * the maximum number of tokens the place can hold.

	 * The capacity must be > 0.
	 * 
	 * @param capacity
	 *            The desired capacity.
	 */
	public void setCapacity(int capacity){
		Validate.bigger(capacity, 0);
		int oldCapacity = this.capacity;
		this.capacity = capacity;
		if (oldCapacity != capacity)
			placeListenerSupport.notifyCapacityChanged(new CapacityEvent>(this, capacity));
	}

	/**
	 * Removes the capacity restriction of the place, i.e.

	 * the maximum number of tokens the place can hold.
	 */
	public void removeCapacity() {
		capacity = -1;
	}

	/**
	 * Checks, if the place is bounded.

	 * Bounded places restrict the number and kind of tokens that can reside in the place.

	 * A capacity of -1 is interpreted as unboundedness.
	 * 
	 * @return true if the place is bounded,

	 *         false otherwise.
	 */
	public boolean isBounded() {
		return getCapacity() > -1;
	}

	/**
	 * checks if this place and the given place have the same relations.
	 * 
	 * @param otherPlace
	 *            The place in question.
	 * @return true if the two places have the same relations;

	 *         false otherwise.
	 */
	public boolean hasEqualRelations(AbstractPlace otherPlace){
		Validate.notNull(otherPlace);
		List incomingRelations = otherPlace.getIncomingRelations();
		List outgoingRelations = otherPlace.getOutgoingRelations();
		if ((this.incomingRelations.size() != incomingRelations.size()) || (this.outgoingRelations.size() != outgoingRelations.size())) {
			return false;
		}
		for (AbstractFlowRelation, ? extends AbstractTransition, S> incoming : incomingRelations) {
			if (!this.containsRelationFrom(incoming.getTransition()))
				return false;
		}
		for (AbstractFlowRelation, ? extends AbstractTransition, S> outgoing : outgoingRelations) {
			if (!this.containsRelationTo(outgoing.getTransition()))
				return false;
		}
		return true;
	}
	
//	@Override
//	protected void setName(String name){
//		Validate.notNull(name);
//		if(!placeListenerSupport.requestNameChangePermission(this, name))
//			throw new ParameterException(ErrorCode.INCONSISTENCY, "A connected Petri net already contains a node with this name.\n Cancel renaming to avoid name clash.");
//		this.name = name;
//	}
	
	public int outDegree(){
		return getOutgoingRelations().size();
	}
	
	public int inDegree(){
		return getIncomingRelations().size();
	}

	// ------- State manipulation -----------------------------------------------------------------------------

	/**
	 * Returns the state of the place in terms of number and kind of tokens.

	 * The returned state should NOT be used to manually add or remove tokens from a place.

	 * Token adding/removal is done by Petri net transitions.
	 * 
	 * @return The actual state of the place.
	 * @see AbstractPlace#state
	 */
	public abstract S getState();

	/**
	 * Sets the state of the place in terms of number and kind of tokens if the place is not already in this state.

	 * Before the state is set, its validity is checked with the help of {@link #validateState(Object)}.

	 * On state changes, the place tells connected transitions to update their state

	 * and calls the method {@link #stateChange(Object, Object)} which can be 

	 * overridden in subclasses to take further actions on state changes.
	 * 
	 * @param state
	 *            The desired state of the place.
	 * @return true if the actual place state was changed to the given state;

	 *         false if the place is already in the given state.
	 * @see #initiateStateChecks()
	 */
	public boolean setState(S state){
		validateState(state);
		if (this.state.equals(state))
			return false;

		S oldState = this.state;
		this.state = state;
		// Tell outgoing transitions to update their state.
		initiateStateChecks();
		// Call state-change method
		stateChange(oldState, state);
		return true;
	}

	/**
	 * Adds all given tokens to the place.

	 * The number and type of tokens to add are defined by type S.
	 * 
	 * @param tokens
	 *            The number and type of tokens to add.
	 * @throws ParameterException
	 *             If the given parameter is null or invalid,

	 *             or if the tokens cannot be added to the place, e.g. due to capacity restrictions.
	 */
	protected abstract void addTokens(S tokens);

	/**
	 * Removes all given tokens from the place.

	 * The number and type of tokens to remove are defined by type S.
	 * 
	 * @param tokens
	 *            The number and type of tokens to remove.
	 * @throws ParameterException
	 *             If the given parameter is null or invalid,

	 *             or if the tokens cannot be removed from the place.
	 */
	protected abstract void removeTokens(S tokens);

	/**
	 * Checks, if the place can consume the given state, i.e.

	 * merging the actual state and the given state does not exceed the places' capacity.

	 * This method does NOT actually "add" the given state to the places' actual state.
	 * 
	 * @param state
	 *            The state to merge.
	 * @return true if the place can consume the state;

	 *         false otherwise.
	 * @throws ParameterException
	 *             if the given state is null.
	 */
	public abstract boolean canConsume(S state);

	/**
	 * Checks if the place state is empty, i.e. the place contains no tokens.

	 * Depending on the state representation this may require different check routines,

	 * which have to be implemented by subclasses.
	 * 
	 * @return true if the place contains not tokens;

	 *         false otherwise.
	 */
	public abstract boolean hasEmptyState();

	/**
	 * Sets the state of the place in empty condition, i.e. removes all tokens from the place.

	 * Depending on the state representation this may require different check routines,

	 * which have to be implemented by subclasses.
	 * @see #getEmptyState()
	 */
	public boolean setEmptyState(){
		S emptyState = getEmptyState();
		if(getState().equals(emptyState))
			return false;
		
		S oldState = getState();
		this.state = emptyState;
		// Tell outgoing transitions to update their state.
		initiateStateChecks();
		// Call state-change method
		stateChange(oldState, emptyState);
		return true;
	}
	
	/**
	 * Gets the state of the place in empty condition.
	 */
	public abstract S getEmptyState();

	/**
	 * This method is called by {@link #setState(Object)} in case of state changes.

	 * It can be overridden in subclasses to take further actions on state changes.
	 * 
	 * @param oldState
	 *            Old place state before change.
	 * @param newState
	 *            New place state after change.
	 */
	protected abstract void stateChange(S oldState, S newState);

	/**
	 * Tells outgoing transitions to update their state.

	 * Depending on token changes outgoing transitions may get enabled/disabled.
	 */
	protected void initiateStateChecks() {

		for (AbstractFlowRelation, ? extends AbstractTransition, S> r : outgoingRelations.values()) {

			r.getTransition().checkState();
		}
		for (AbstractFlowRelation, ? extends AbstractTransition, S> r : incomingRelations.values()) {

			r.getTransition().checkState();
		}
	}

	// ------- Validity -------------------------------------------------------------------------------

	/**
	 * Checks if the Petri net place is valid.

	 * Subclasses may define the validity of a net place e.g. in terms of specific constraints and must throw PNValidationExceptions in case any constraint is violated.
	 * 
	 * @throws PNValidationException
	 */
	public void checkValidity() throws PNValidationException {}

	// ------- Validation methods ----------------------------------------------------------------------

	/**
	 * Checks if the given state is valid.

	 * The exact definition of validity can be defined in subclasses by overriding this method.

	 * Default behavior is to check null-pointers.
	 * 
	 * @param state
	 *            The state to validate.
	 * @throws ParameterException
	 *             If the given state is null.
	 */
	protected void validateState(S state){
		Validate.notNull(state);
	}

	// ------- Listener support -----------------------------------------------------------------------

	/**
	 * Adds a token listener.
	 * 
	 * @param l
	 *            The token listener to add.
	 * @throws ParameterException
	 *             If the listener reference is null.
	 */
	public void addTokenListener(TokenListener> l){
		tokenListenerSupport.addListener(l);
	}

	/**
	 * Removes a token listener.
	 * 
	 * @param l
	 *            The token listener to remove.
	 * @throws ParameterException
	 *             If the listener reference is null.
	 */
	public void removeTokenListener(TokenListener> l){
		tokenListenerSupport.removeListener(l);
	}

	/**
	 * Adds a capacity listener.
	 * @param l The capacity listener to add.
	 * @throws ParameterException If the listener reference is null.
	 */
	public void addPlaceListener(PlaceListener> l){
		placeListenerSupport.addListener(l);
	}

	/**
	 * Removes a capacity listener.
	 * @param l The capacity listener to remove.
	 * @throws ParameterException If the listener reference is null.
	 */
	public void removePlaceListener(PlaceListener> l){
		placeListenerSupport.removeListener(l);
	}

	@Override
	protected abstract AbstractPlace newInstance(String name);

	// ------- hashCode and equals --------------------------------------------------------------------

	@Override
	public int hashCode() {
		final int prime = 31;
		int result = super.hashCode();
		result = prime * result + capacity;
		result = prime * result + ((state == null) ? 0 : state.hashCode());
		return result;
	}

	@Override
	public boolean equals(Object obj) {
		if (this == obj) {
			return true;
		}
		if (!super.equals(obj)) {
			return false;
		}
		if (getClass() != obj.getClass()) {
			return false;
		}
		@SuppressWarnings("unchecked")
		AbstractPlace other = (AbstractPlace) obj;
		if (capacity != other.capacity) {
			return false;
		}
		if (state == null) {
			if (other.state != null) {
				return false;
			}
		} else if (!state.equals(other.state)) {
			return false;
		}
		return true;
	}

	// ------- clone ----------------------------------------------------------------------------------

	@Override
	public AbstractPlace clone() {
		@SuppressWarnings("unchecked")
		AbstractPlace result = (AbstractPlace) super.clone();
		cloneCapacity(result);
		result.setState(getState());
		return result;
	}

	protected void cloneCapacity(AbstractPlace clone){
		if (getCapacity() > 0)
			clone.setCapacity(getCapacity());
	}

}