place.java

Rakiura JFern是一个非常轻型的带有模拟器的Petri网络框架

// This is copyrighted source file, part of Rakiura JFern package. 
// See the file LICENSE for copyright information and the terms and conditions
// for copying, distributing and modifications of Rakiura JFern package.
// Copyright (C) 1999-2002 by Mariusz Nowostawski and others  [http://www.rakiura.org]

package org.rakiura.cpn;

/**/
import java.util.ArrayList;
import java.util.Collection;
import java.util.Iterator;
import java.util.List;

import org.rakiura.cpn.event.PlaceListener;
import org.rakiura.cpn.event.TokensAddedEvent;
import org.rakiura.cpn.event.TokensRemovedEvent;


/**
 * Represents a Place in the JFern Petri Net. Place is one of the elementary 
 * nodes in the Petri Net graph. Place contains tokens which are kept
 * inside a single multiset structure.
 *
 * 
 *<br><br>
 * Place.java<br>
 * Created: Mon Sep 25 21:23:17 2000<br>
 *
 *@author  <a href="[e-mail]">Mariusz Nowostawski</a>
 *@version 2.1.0 $Revision: 1.12 $
 *@since 2.0
 */
public class Place extends Node {
  
  /**/
  private Multiset multiset;

  /**/
  private List listeners = new ArrayList();
  private List fusionPlaces = new ArrayList();

  /**/
  private List inputs = new ArrayList(10);

  /**/
  private List outputs = new ArrayList(10);
  


  /**
   * Creates a new <code>Place</code> instance.
   */
  public Place() {
    this.multiset = new Multiset();
  }

  /**
   * Creates a new <code>Place</code> instance 
   * with a given Place name.
   * @param aName this place name.
   */
  public Place(final String aName) {
    super(aName);
    this.multiset = new Multiset();
  }

  /**
   * Creates a new <code>Place</code> instance, 
   * initialized with a given multiset.
   * @param aMultiset an initial <code>multiset</code>
   */
  public Place(final Collection aMultiset) {
    this.multiset = new Multiset(aMultiset);
  }

  /**
   * Adds an input Arc. This method is not for the user to call
   * directly, it is called by newly created arcs which plug
   * themselves automatically to the appropriate place. 
   *@return this place. 
   */
  public Place addInput(final InputArc anArc){
    this.inputs.add(anArc);
    return this;
  }

  /**
   * Adds an output Arc. This method is not for the user to call
   * directly, it is called by newly created arcs which plug
   * themselves automatically to the appropriate place. 
   *@return this Place. 
   */
  public Place addOutput(final OutputArc anArc){
    this.outputs.add(anArc);
    return this;
  }

  /** 
   * Returns list of all input arcs from this place.
   * <b>Note:</b> input arcs go from this place to a given 
   * transition, so in a sense, from the place point of view
   * could be treated as outgoing arcs.
   *@return set of all input arcs from this place.
   */
  public List inputArcs(){ return this.inputs; }

  /** 
   * Returns list of all output arcs to this place.
   * <b>Note:</b> output arcs go from a given transition
   * to this place, so in a sense, from the place point of view
   * could be treated as incoming arcs.
   *@return set of all output arcs to this place.
   */
  public List outputArcs(){ return this.outputs; }



  /**
   * Returns all the tokens for this place.
   * Returned is the reference to the copy of this place multiset. 
   * Use this method with caution, do not manipulate tokens via
   * the returned multiset, as it will have no effect on 
   * the actual state of this place - use token manipulation 
   * methods from the Place API.
   *@return this place collection of tokens
   *@see #addToken
   *@see #removeToken
   */
  public Multiset getTokens() {
    return new Multiset(this.multiset);
  }

  /**
   * Adds given tokens to this place.
   *@param aMultiset a <code>multiset</code> of tokens.
   */
  public void addTokens(final Collection aMultiset) {
    addTokensQuietly(aMultiset);
    notifyFusionAdded(new TokensAddedEvent(this, new Multiset(aMultiset)));
  }

  /**
   * Adds given tokens to this place without firing the event.
   *@param aMultiset a <code>multiset</code> of tokens.
   */
  void addTokensQuietly(final Collection aMultiset) {
    this.multiset.addAll(aMultiset);
    if (this.listeners.size() > 0) {
      fireTokensAddedEvent(new TokensAddedEvent(this, new Multiset(aMultiset)));
    }
  }


  /**
   * Adds new token to this place. 
   * Adds a new token to the existing place multiset.
   *@param aToken an additonal token for this place. 
   */
  public void addToken(final Object aToken) {
    this.multiset.add(aToken);
    final TokensAddedEvent event = new TokensAddedEvent(this, new Multiset(aToken));
    if (this.listeners.size() > 0) {
      fireTokensAddedEvent(event);
    }
    if (this.fusionPlaces.size() > 0) {
      notifyFusionAdded(event);
    }
  }
  
  /**
   * Removes all tokens from the given multiset from this place.
   *@param aMultiset multiset containing tokens to be removed.   
   */
  public void removeTokens(final Collection aMultiset) {
    removeTokensQuietly(aMultiset);
    notifyFusionRemoved(new TokensRemovedEvent(this, new Multiset(aMultiset)));
  }

  /**
   * Removes all tokens from the given multiset from this place without
   * firing the event.
   *@param aMultiset multiset containing tokens to be removed.   
   */
  void removeTokensQuietly(final Collection aMultiset) {
    this.multiset.removeAll(aMultiset);
    if (this.listeners.size() > 0) {
      fireTokensRemovedEvent(new TokensRemovedEvent(this, new Multiset(aMultiset)));
    }
  }

  /**
   * Removes given token from the given multiset from this place.
   *@param aToken token to be removed.
   *@return <code>true</code> if the token was succesfully removed,
   * <code>false</code> if the token was not present in the place and 
   * was not removed.
   */
  public boolean removeToken(final Object aToken) {
    final boolean result = this.multiset.remove(aToken);
    final TokensRemovedEvent event = new TokensRemovedEvent(this, new Multiset(aToken));
    if (this.listeners.size() > 0) {
      fireTokensRemovedEvent(event);
    }    
    if (this.fusionPlaces.size() > 0) {
      notifyFusionRemoved(event);
    }
    return result;
  }

  /**
   * Removes all the tokens from this place.
   */
  public void clearTokens() {
    final TokensRemovedEvent event = new TokensRemovedEvent(this, new Multiset(this.multiset));
    this.multiset.clear();
    if (this.listeners.size() > 0) {
      fireTokensRemovedEvent(event); 
    }
    if (this.fusionPlaces.size() > 0) {
      notifyFusionRemoved(event);
    }
  }

  /**
   * Visitor pattern.
   *@param aVisitor a <code>NetVisitor</code> value
   *@return a <code>NetElement</code> value
   */
  public NetElement apply(final NetVisitor aVisitor) {
    aVisitor.place(this);
    return this;
  }


  /**
   * Registers a given PlaceListener with this place.
   *@param aListener a <code>PlaceListener</code> to 
   * be registered with this Place.
   */
  public void addPlaceListener(final PlaceListener aListener) {
    this.listeners.add(aListener);
  }

  /**
   * Deregisters a given PlaceListener from this place.
   *@param aListener a <code>PlaceListener</code> to 
   * be removed with this Place.
   */
  public void removePlaceListener(final PlaceListener aListener) {
    this.listeners.remove(aListener);
  }

  /**
   * Notifies all listeners about tokens being removed from this place.
   *@param anEvent a TokensRemovedEvent
   */
  protected void fireTokensRemovedEvent(final TokensRemovedEvent anEvent) {
    final Iterator l = this.listeners.iterator();
    while (l.hasNext()) {
      ((PlaceListener) l.next()).notify(anEvent);
    }
  }

  /**
   * Notifies all listeners about tokens being added to this place.
   *@param anEvent tokens added event
   */
  private void fireTokensAddedEvent(final TokensAddedEvent anEvent) {
    final Iterator l = this.listeners.iterator();
    while (l.hasNext()) {
      ((PlaceListener) l.next()).notify(anEvent);
    }
  }



  /**
   * Notifies all listeners about tokens being removed from this place.
   *@param anEvent a TokensRemovedEvent
   */
  void notifyFusionRemoved(final TokensRemovedEvent anEvent) {
    final Iterator l = this.fusionPlaces.iterator();
    while (l.hasNext()) {
      ((FusionPlace) l.next()).notify(anEvent);
    }
  }

  /**
   * Notifies all listeners about tokens being added to this place.
   *@param anEvent tokens added event
   */
  void notifyFusionAdded(final TokensAddedEvent anEvent) {
    final Iterator l = this.fusionPlaces.iterator();
    while (l.hasNext()) {
      ((FusionPlace) l.next()).notify(anEvent);
    }
  }

  
  void addFusionPlace(FusionPlace aPlace) {
    this.fusionPlaces.add(aPlace);
  }
  
  void removeFusionPlace(final FusionPlace aPlace) {
    this.fusionPlaces.remove(aPlace);
  }


  /**
   * Returns human readable representiation of this place.
   *@return a <code>String</code> value.
   */
  public String toString() {
    final String res = "Place: " + getName() + " ";
    return res + this.multiset.toString();
  }

} // Place
//////////////////// end of file ////////////////////