moved examples under doc per Erik

13 files changed, 767 insertions, 0 deletions

diff --git a/docs/dist/doc/examples/telecom/AbstractSimulation.java b/docs/dist/doc/examples/telecom/AbstractSimulation.java
new file mode 100644
index 000000000..1c44af7a7
--- /dev/null
+++ b/docs/dist/doc/examples/telecom/AbstractSimulation.java
@@ -0,0 +1,80 @@
+/*
+
+Copyright (c) Xerox Corporation 1998-2002.  All rights reserved.
+
+Use and copying of this software and preparation of derivative works based
+upon this software are permitted.  Any distribution of this software or
+derivative works must comply with all applicable United States export control
+laws.
+
+This software is made available AS IS, and Xerox Corporation makes no warranty
+about the software, its performance or its conformity to any specification.
+
+|<---            this code is formatted to fit into 80 columns             --->|
+|<---            this code is formatted to fit into 80 columns             --->|
+|<---            this code is formatted to fit into 80 columns             --->|
+
+*/
+package telecom;
+
+public abstract class AbstractSimulation {
+
+    public static AbstractSimulation simulation;
+
+    /**
+     * Creates objects and puts them to work.
+     */
+    public void run() {
+        Customer jim = new Customer("Jim", 650);
+        Customer mik = new Customer("Mik", 650);
+        Customer crista = new Customer("Crista", 415);
+
+        say("jim calls mik...");
+        Call c1 = jim.call(mik);
+        wait(1.0);
+        say("mik accepts...");
+        mik.pickup(c1);
+        wait(2.0);
+        say("jim hangs up...");
+        jim.hangup(c1);
+        report(jim);
+        report(mik);
+        report(crista);
+
+        say("mik calls crista...");
+        Call c2 = mik.call(crista);
+        say("crista accepts...");
+        crista.pickup(c2);
+        wait(1.5);
+        say("crista hangs up...");
+        crista.hangup(c2);
+        report(jim);
+        report(mik);
+        report(crista);
+    }
+
+    /**
+     * Print a report of the connection time for customer
+     */
+    abstract protected void report(Customer c);
+
+    /**
+     * Wait 0.1 seconds per "second" for simulation
+     */
+    protected static void wait(double seconds) {
+        Object dummy = new Object();
+        synchronized (dummy) {
+	    //XXX cheat and only wait 0.1 seconds per second
+            try {dummy.wait((long)(seconds*100)); }
+            catch (Exception e) {}
+        }
+    }
+
+    /**
+     * Put a message on standard output
+     */
+    protected static void say(String s){
+	System.out.println(s);
+    }
+
+}
diff --git a/docs/dist/doc/examples/telecom/BasicSimulation.java b/docs/dist/doc/examples/telecom/BasicSimulation.java
new file mode 100644
index 000000000..ab7426376
--- /dev/null
+++ b/docs/dist/doc/examples/telecom/BasicSimulation.java
@@ -0,0 +1,34 @@
+/*
+
+Copyright (c) Xerox Corporation 1998-2002.  All rights reserved.
+
+Use and copying of this software and preparation of derivative works based
+upon this software are permitted.  Any distribution of this software or
+derivative works must comply with all applicable United States export control
+laws.
+
+This software is made available AS IS, and Xerox Corporation makes no warranty
+about the software, its performance or its conformity to any specification.
+
+|<---            this code is formatted to fit into 80 columns             --->|
+|<---            this code is formatted to fit into 80 columns             --->|
+|<---            this code is formatted to fit into 80 columns             --->|
+
+*/
+package telecom;
+
+/**
+ * This simulation subclass implements AbstractSimulation.run(..)
+ * with  a test script for the telecom system with only the
+ * basic objects.
+ */
+public class BasicSimulation extends AbstractSimulation {
+
+    public static void main(String[] args){
+	simulation = new BasicSimulation();
+	simulation.run();
+    }
+
+    protected void report(Customer c) { }
+
+}
diff --git a/docs/dist/doc/examples/telecom/Billing.java b/docs/dist/doc/examples/telecom/Billing.java
new file mode 100644
index 000000000..c69ca758c
--- /dev/null
+++ b/docs/dist/doc/examples/telecom/Billing.java
@@ -0,0 +1,80 @@
+/*
+
+Copyright (c) Xerox Corporation 1998-2002.  All rights reserved.
+
+Use and copying of this software and preparation of derivative works based
+upon this software are permitted.  Any distribution of this software or
+derivative works must comply with all applicable United States export control
+laws.
+
+This software is made available AS IS, and Xerox Corporation makes no warranty
+about the software, its performance or its conformity to any specification.
+
+|<---            this code is formatted to fit into 80 columns             --->|
+|<---            this code is formatted to fit into 80 columns             --->|
+|<---            this code is formatted to fit into 80 columns             --->|
+
+*/
+
+package telecom;
+/**
+ * The Billing aspect deals with... billing.
+ * How much money did each connection cost?
+ * How much money did each call cost?
+ * How much money is being debited to a customer?
+ * This aspect can be used by other parts of the system. (not in this example)
+ *
+ * Billing can depend many things, such as timing, the type of the connection,
+ * some special discounts the customer has, special features, etc. In here,
+ * it depends only on timing and on the type of the connection.
+ */
+public aspect Billing {
+    // domination required to get advice on endtiming in the right order
+    declare dominates: Billing, Timing;
+
+    public static final long LOCAL_RATE = 3;
+    public static final long LONG_DISTANCE_RATE = 10;
+
+
+    public Customer Connection.payer;
+    public Customer getPayer(Connection conn) { return conn.payer; }
+    /**
+     * Caller pays for the call
+     */
+    after(Customer cust) returning (Connection conn):
+        args(cust, ..) && call(Connection+.new(..)) {
+        conn.payer = cust;
+    }
+
+    /**
+     * Connections give the appropriate call rate
+     */
+    public abstract long Connection.callRate();
+
+
+    public long LongDistance.callRate() { return LONG_DISTANCE_RATE; }
+    public long Local.callRate() { return LOCAL_RATE; }
+
+
+    /**
+     * When timing stops, calculate and add the charge from the
+     * connection time
+     */
+    after(Connection conn): Timing.endTiming(conn) {
+        long time = Timing.aspectOf().getTimer(conn).getTime();
+        long rate = conn.callRate();
+        long cost = rate * time;
+        getPayer(conn).addCharge(cost);
+    }
+
+
+    /**
+     * Customers have a bill paying aspect with state
+     */
+    public long Customer.totalCharge = 0;
+    public long getTotalCharge(Customer cust) { return cust.totalCharge; }
+
+    public void Customer.addCharge(long charge){
+        totalCharge += charge;
+    }
+}
diff --git a/docs/dist/doc/examples/telecom/BillingSimulation.java b/docs/dist/doc/examples/telecom/BillingSimulation.java
new file mode 100644
index 000000000..09f273ff6
--- /dev/null
+++ b/docs/dist/doc/examples/telecom/BillingSimulation.java
@@ -0,0 +1,44 @@
+/*
+
+Copyright (c) Xerox Corporation 1998-2002.  All rights reserved.
+
+Use and copying of this software and preparation of derivative works based
+upon this software are permitted.  Any distribution of this software or
+derivative works must comply with all applicable United States export control
+laws.
+
+This software is made available AS IS, and Xerox Corporation makes no warranty
+about the software, its performance or its conformity to any specification.
+
+|<---            this code is formatted to fit into 80 columns             --->|
+|<---            this code is formatted to fit into 80 columns             --->|
+|<---            this code is formatted to fit into 80 columns             --->|
+
+*/
+package telecom;
+
+/**
+ * This simulation subclass implements AbstractSimulation.report(..)
+ * 
+ */
+public class BillingSimulation extends AbstractSimulation {
+
+    public static void main(String[] args){
+	System.out.println("\n... Billing simulation 2 ...\n");
+	simulation = new BillingSimulation();
+	simulation.run();
+    }
+
+    /**
+     * Print a report of the connection time and the bill for customer
+     */
+    protected void report(Customer c){
+        Timing t = Timing.aspectOf();
+        Billing b = Billing.aspectOf();
+        System.out.println(c + " has been connected for "
+			   + t.getTotalConnectTime(c)
+			   + " seconds and has a bill of "
+			   + b.getTotalCharge(c));
+    }
+}
+
diff --git a/docs/dist/doc/examples/telecom/Call.java b/docs/dist/doc/examples/telecom/Call.java
new file mode 100644
index 000000000..738d2d348
--- /dev/null
+++ b/docs/dist/doc/examples/telecom/Call.java
@@ -0,0 +1,97 @@
+/*
+
+Copyright (c) Xerox Corporation 1998-2002.  All rights reserved.
+
+Use and copying of this software and preparation of derivative works based
+upon this software are permitted.  Any distribution of this software or
+derivative works must comply with all applicable United States export control
+laws.
+
+This software is made available AS IS, and Xerox Corporation makes no warranty
+about the software, its performance or its conformity to any specification.
+
+|<---            this code is formatted to fit into 80 columns             --->|
+|<---            this code is formatted to fit into 80 columns             --->|
+|<---            this code is formatted to fit into 80 columns             --->|
+
+*/
+package telecom;
+import java.util.Vector;
+import java.util.Enumeration;
+
+/**
+ * A call supports the process of a customer trying to
+ * connect to others.
+ */
+public class Call {
+
+    private Customer caller, receiver;
+    private Vector connections = new Vector();
+
+    /**
+     * Create a new call connecting caller to receiver
+     * with a new connection. This should really only be
+     * called by Customer.call(..)
+     */
+    public Call(Customer caller, Customer receiver) {
+        this.caller = caller;
+        this.receiver = receiver;
+        Connection c;
+        if (receiver.localTo(caller)) {
+	    c = new Local(caller, receiver);
+        } else {
+	    c = new LongDistance(caller, receiver);
+        }
+        connections.add(c);
+    }
+
+    /**
+     * picking up a call completes the current connection
+     * (this means that you shouldnt merge calls until
+     * they are completed)
+     */
+    public void pickup() {
+    	Connection connection = (Connection)connections.lastElement();
+        connection.complete();
+    }
+
+
+    /**
+     * Is the call in a connected state?
+     */
+    public boolean isConnected(){
+	return ((Connection)connections.lastElement()).getState()
+            == Connection.COMPLETE;
+    }
+
+    /**
+     * hanging up a call drops the connection
+     */
+    public void hangup(Customer c) {
+        for(Enumeration e = connections.elements(); e.hasMoreElements();) {
+	    ((Connection)e.nextElement()).drop();
+        }
+    }
+
+    /**
+     * is Customer c one of the customers in this call?
+     */
+    public boolean includes(Customer c){
+	boolean result = false;
+	for(Enumeration e = connections.elements(); e.hasMoreElements();) {
+	    result = result || ((Connection)e.nextElement()).connects(c);
+	}
+	return result;
+    }
+
+    /**
+     * Merge all connections from call 'other' into 'this'
+     */
+    public void merge(Call other){
+	for(Enumeration e = other.connections.elements(); e.hasMoreElements();){
+	    Connection conn = (Connection)e.nextElement();
+	    other.connections.remove(conn);
+	    connections.addElement(conn);
+	}
+    }
+}
diff --git a/docs/dist/doc/examples/telecom/Connection.java b/docs/dist/doc/examples/telecom/Connection.java
new file mode 100644
index 000000000..7d54ec843
--- /dev/null
+++ b/docs/dist/doc/examples/telecom/Connection.java
@@ -0,0 +1,87 @@
+/*
+
+Copyright (c) Xerox Corporation 1998-2002.  All rights reserved.
+
+Use and copying of this software and preparation of derivative works based
+upon this software are permitted.  Any distribution of this software or
+derivative works must comply with all applicable United States export control
+laws.
+ 
+This software is made available AS IS, and Xerox Corporation makes no warranty
+about the software, its performance or its conformity to any specification.
+
+|<---            this code is formatted to fit into 80 columns             --->|
+|<---            this code is formatted to fit into 80 columns             --->|
+|<---            this code is formatted to fit into 80 columns             --->|
+
+*/
+package telecom;
+
+/**
+ * Connections are circuits between customers
+ * There are two kinds: local and long distance
+ * see subclasses at the end of this file.
+ */
+public abstract class Connection {
+
+    public static final int PENDING = 0;
+    public static final int COMPLETE = 1;
+    public static final int DROPPED = 2;
+
+    Customer caller, receiver;
+    private int state = PENDING;
+
+    /**
+     * Creatte a new Connection between a and b
+     */
+    Connection(Customer a, Customer b) {
+        this.caller = a;
+        this.receiver = b;
+    }
+
+    /**
+     * what is the state of the connection?
+     */
+    public int getState(){
+	return state;
+    }
+
+    /**
+     * get the customer who initiated this connection
+     */
+    public Customer getCaller() { return caller; }
+
+    /**
+     * get the customer who received this connection
+     */
+    public Customer getReceiver() { return receiver; }
+
+    /**
+     * Called when a call is picked up.  This means the b side has picked up
+     * and the connection should now complete itself and start passing data.
+     */
+    void complete() {
+        state = COMPLETE;
+        System.out.println("connection completed");
+    }
+
+    /**
+     * Called when the connection is dropped from a call.  Is intended to
+     * free up any resources the connection was consuming.
+     */
+    void drop() {
+	state = DROPPED;
+        System.out.println("connection dropped");
+    }
+
+    /**
+     * Is customer c connected by this connection?
+     */
+    public boolean connects(Customer c){
+	return (caller == c || receiver == c);
+    }
+
+}
+
+
+
diff --git a/docs/dist/doc/examples/telecom/Customer.java b/docs/dist/doc/examples/telecom/Customer.java
new file mode 100644
index 000000000..1e099984c
--- /dev/null
+++ b/docs/dist/doc/examples/telecom/Customer.java
@@ -0,0 +1,112 @@
+/*
+
+Copyright (c) Xerox Corporation 1998-2002.  All rights reserved.
+
+Use and copying of this software and preparation of derivative works based
+upon this software are permitted.  Any distribution of this software or
+derivative works must comply with all applicable United States export control
+laws.
+ 
+This software is made available AS IS, and Xerox Corporation makes no warranty
+about the software, its performance or its conformity to any specification.
+
+|<---            this code is formatted to fit into 80 columns             --->|
+|<---            this code is formatted to fit into 80 columns             --->|
+|<---            this code is formatted to fit into 80 columns             --->|
+
+*/
+package telecom;
+import java.util.Vector;
+
+/**
+ * Customers have a unique id (name in this case for didactic purposes
+ * but it could be telephone number) and area code.
+ * They also have protocol for managing calls: call, pickup, etc.
+ */
+public class Customer {
+
+    private String name;
+    private int areacode;
+    private Vector calls = new Vector();
+
+    /**
+     * unregister a call
+     */
+    protected void removeCall(Call c){
+	calls.removeElement(c);
+    }
+
+    /**
+     * register a call
+     */
+    protected void addCall(Call c){
+	calls.addElement(c);
+    }
+
+    /**
+     * Make a new customer with given name
+     */
+    public Customer(String name, int areacode) {
+        this.name = name;
+        this.areacode = areacode;
+    }
+
+    /**
+     * String rendition of customer
+     */
+    public String toString() {
+        return name + "(" + areacode + ")";
+    }
+
+    /**
+     * what area is the customer in?
+     */
+    public int getAreacode(){
+	return areacode;
+    }
+
+    /**
+     * Is the other customer in the same area?
+     */
+    public boolean localTo(Customer other){
+	return areacode == other.areacode;
+    }
+
+    /**
+     * Make a new call to receiver
+     */
+    public Call call(Customer receiver) {
+        Call call = new Call(this, receiver);
+        addCall(call);
+        return call;
+    }
+
+    /**
+     * pick up a call
+     */
+    public void pickup(Call call) {
+        call.pickup();
+        addCall(call);
+    }
+
+    /**
+     * hang up a call
+     */
+    public void hangup(Call call) {
+	call.hangup(this);
+	removeCall(call);
+    }
+
+    /**
+     * Merge a pair of calls -- conference them
+     * PRE: call1.includes(this)
+     *      call2.includes(this)
+     *      call1.connected()
+     *      call2.connected()
+     * POST: call1 includes all customers connected by call1@pre and call2@pre
+     */
+    public void merge(Call call1, Call call2){
+	call1.merge(call2);
+	removeCall(call2);
+    }
+}
diff --git a/docs/dist/doc/examples/telecom/Local.java b/docs/dist/doc/examples/telecom/Local.java
new file mode 100644
index 000000000..e0bc02679
--- /dev/null
+++ b/docs/dist/doc/examples/telecom/Local.java
@@ -0,0 +1,26 @@
+/*
+
+Copyright (c) Xerox Corporation 1998-2002.  All rights reserved.
+
+Use and copying of this software and preparation of derivative works based
+upon this software are permitted.  Any distribution of this software or
+derivative works must comply with all applicable United States export control
+laws.
+ 
+This software is made available AS IS, and Xerox Corporation makes no warranty
+about the software, its performance or its conformity to any specification.
+
+|<---            this code is formatted to fit into 80 columns             --->|
+|<---            this code is formatted to fit into 80 columns             --->|
+|<---            this code is formatted to fit into 80 columns             --->|
+
+*/
+package telecom;
+
+public class Local extends Connection {
+    Local(Customer a, Customer b) {
+	super(a, b);
+	System.out.println("[new local connection from " + 
+	   a + " to " + b + "]");
+    }
+}
diff --git a/docs/dist/doc/examples/telecom/LongDistance.java b/docs/dist/doc/examples/telecom/LongDistance.java
new file mode 100644
index 000000000..b2ed6eb7d
--- /dev/null
+++ b/docs/dist/doc/examples/telecom/LongDistance.java
@@ -0,0 +1,26 @@
+/*
+
+Copyright (c) Xerox Corporation 1998-2002.  All rights reserved.
+
+Use and copying of this software and preparation of derivative works based
+upon this software are permitted.  Any distribution of this software or
+derivative works must comply with all applicable United States export control
+laws.
+ 
+This software is made available AS IS, and Xerox Corporation makes no warranty
+about the software, its performance or its conformity to any specification.
+
+|<---            this code is formatted to fit into 80 columns             --->|
+|<---            this code is formatted to fit into 80 columns             --->|
+|<---            this code is formatted to fit into 80 columns             --->|
+
+*/
+package telecom;
+
+public class LongDistance extends Connection {
+    LongDistance(Customer a, Customer b) {
+	super(a, b);
+	System.out.println("[new long distance connection from " + 
+	    a + " to " + b + "]");
+    }
+}
diff --git a/docs/dist/doc/examples/telecom/Timer.java b/docs/dist/doc/examples/telecom/Timer.java
new file mode 100644
index 000000000..813ae3a0d
--- /dev/null
+++ b/docs/dist/doc/examples/telecom/Timer.java
@@ -0,0 +1,50 @@
+/*
+
+Copyright (c) Xerox Corporation 1998-2002.  All rights reserved.
+
+Use and copying of this software and preparation of derivative works based
+upon this software are permitted.  Any distribution of this software or
+derivative works must comply with all applicable United States export control
+laws.
+ 
+This software is made available AS IS, and Xerox Corporation makes no warranty
+about the software, its performance or its conformity to any specification.
+
+|<---            this code is formatted to fit into 80 columns             --->|
+|<---            this code is formatted to fit into 80 columns             --->|
+|<---            this code is formatted to fit into 80 columns             --->|
+
+*/
+package telecom;
+
+
+/**
+ * Simple timer machine used to record elapsed time
+ */
+public class Timer {
+    public long startTime, stopTime;
+
+    /**
+     * set the start time
+     */
+    public void start() {
+        startTime = System.currentTimeMillis();
+        stopTime = startTime;
+    }
+
+    /**
+     * set the end time
+     */
+    public void stop() {
+        stopTime = System.currentTimeMillis();
+    }
+
+    /**
+     * set how much time passed between last start and stop?
+     */
+    public long getTime() {
+        return stopTime - startTime;
+    }
+}
+
+
diff --git a/docs/dist/doc/examples/telecom/TimerLog.java b/docs/dist/doc/examples/telecom/TimerLog.java
new file mode 100644
index 000000000..4591894dc
--- /dev/null
+++ b/docs/dist/doc/examples/telecom/TimerLog.java
@@ -0,0 +1,29 @@
+/*
+
+Copyright (c) Xerox Corporation 1998-2002.  All rights reserved.
+
+Use and copying of this software and preparation of derivative works based
+upon this software are permitted.  Any distribution of this software or
+derivative works must comply with all applicable United States export control
+laws.
+
+This software is made available AS IS, and Xerox Corporation makes no warranty
+about the software, its performance or its conformity to any specification.
+
+|<---            this code is formatted to fit into 80 columns             --->|
+|<---            this code is formatted to fit into 80 columns             --->|
+|<---            this code is formatted to fit into 80 columns             --->|
+
+*/
+package telecom;
+
+public aspect TimerLog {
+
+    after(Timer t): target(t) && call(* Timer.start())  {
+      System.err.println("Timer started: " + t.startTime);
+    }
+
+    after(Timer t): target(t) && call(* Timer.stop()) {
+      System.err.println("Timer stopped: " + t.stopTime);
+    }
+}
diff --git a/docs/dist/doc/examples/telecom/Timing.java b/docs/dist/doc/examples/telecom/Timing.java
new file mode 100644
index 000000000..f40bd0fca
--- /dev/null
+++ b/docs/dist/doc/examples/telecom/Timing.java
@@ -0,0 +1,62 @@
+/*
+
+Copyright (c) Xerox Corporation 1998-2002.  All rights reserved.
+
+Use and copying of this software and preparation of derivative works based
+upon this software are permitted.  Any distribution of this software or
+derivative works must comply with all applicable United States export control
+laws.
+
+This software is made available AS IS, and Xerox Corporation makes no warranty
+about the software, its performance or its conformity to any specification.
+
+|<---            this code is formatted to fit into 80 columns             --->|
+|<---            this code is formatted to fit into 80 columns             --->|
+|<---            this code is formatted to fit into 80 columns             --->|
+
+*/
+package telecom;
+
+/**
+ * The Timing aspect is concerned with the duration
+ * of connections and with customer's cumulative
+ * connection time.
+ */
+public aspect Timing {
+
+    /**
+     * Every Customer has a total connection time
+     */
+    public long Customer.totalConnectTime = 0;
+  
+    public long getTotalConnectTime(Customer cust) { 
+        return cust.totalConnectTime; 
+    }
+    /**
+     * Every connection has a timer
+     */
+    private Timer Connection.timer = new Timer();
+    public Timer getTimer(Connection conn) { return conn.timer; }
+
+    /**
+     * Start the timer when call completed
+     */
+    after (Connection c): target(c) && call(void Connection.complete()) {
+        getTimer(c).start();
+    }
+
+    /**
+     * When to stop the timer
+     */
+    pointcut endTiming(Connection c): target(c) && 
+        call(void Connection.drop());
+
+    /**
+     * Stop the timer when call dropped and update the involved parties
+     */
+    after(Connection c): endTiming(c) {
+        getTimer(c).stop();
+        c.getCaller().totalConnectTime += getTimer(c).getTime();
+        c.getReceiver().totalConnectTime += getTimer(c).getTime();
+    }
+}
diff --git a/docs/dist/doc/examples/telecom/TimingSimulation.java b/docs/dist/doc/examples/telecom/TimingSimulation.java
new file mode 100644
index 000000000..309563769
--- /dev/null
+++ b/docs/dist/doc/examples/telecom/TimingSimulation.java
@@ -0,0 +1,40 @@
+/*
+
+Copyright (c) Xerox Corporation 1998-2002.  All rights reserved.
+
+Use and copying of this software and preparation of derivative works based
+upon this software are permitted.  Any distribution of this software or
+derivative works must comply with all applicable United States export control
+laws.
+
+This software is made available AS IS, and Xerox Corporation makes no warranty
+about the software, its performance or its conformity to any specification.
+
+|<---            this code is formatted to fit into 80 columns             --->|
+|<---            this code is formatted to fit into 80 columns             --->|
+|<---            this code is formatted to fit into 80 columns             --->|
+
+*/
+package telecom;
+
+/**
+ * This simulation subclass implements AbstractSimulation.report(..)
+ * 
+ */
+public class TimingSimulation extends AbstractSimulation {
+
+    public static void main(String[] args){
+	System.out.println("\n... Timing simulation 2 ...\n");
+	simulation = new TimingSimulation();
+	simulation.run();
+    }
+
+    /**
+     * Print a report of the connection time for customer
+     */
+    protected void report(Customer c){
+        Timing t = Timing.aspectOf();
+        System.out.println(c + " spent " + t.getTotalConnectTime(c));
+    }
+
+}