1/*
2 * Copyright 2007 the original author or authors.
3 *
4 * Licensed under the Apache License, Version 2.0 (the "License");
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
7 *
8 *      http://www.apache.org/licenses/LICENSE-2.0
9 *
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
15 */
16package org.mockftpserver.core.command;
17
18import org.mockftpserver.core.util.Assert;
19import org.mockftpserver.core.util.AssertFailedException;
20
21import java.net.InetAddress;
22import java.util.Collections;
23import java.util.Date;
24import java.util.HashMap;
25import java.util.Map;
26import java.util.Set;
27
28/**
29 * Represents information about a single FTP Command invocation. Manages and provides access to
30 * the Command, the host address (<code>InetAddress</code>) of the client that submitted the
31 * Command and the timestamp of the Command submission.
32 * <p>
33 * This class also supports storing zero or more arbitrary mappings of <i>key</i> to value, where <i>key</i> is
34 * a String and <i>value</i> is any Object. Convenience methods are provided that enable retrieving
35 * type-specific data by its <i>key</i>. The data stored in an {@link InvocationRecord} is CommandHandler-specific.
36 * <p>
37 * The {@link #lock()} method makes an instance of this class immutable. After an instance is locked,
38 * calling the {@link #set(String, Object)} method will throw an <code>AssertFailedException</code>.
39 *
40 * @author Chris Mair
41 * @version $Revision$ - $Date$
42 */
43public class InvocationRecord {
44
45    private Command command;
46    private Date time;
47    private InetAddress clientHost;
48    private Map data = new HashMap();
49    private boolean locked = false;
50
51    /**
52     * Create a new instance
53     *
54     * @param command    - the Command
55     * @param clientHost - the client host
56     */
57    public InvocationRecord(Command command, InetAddress clientHost) {
58        this.command = command;
59        this.time = new Date();
60        this.clientHost = clientHost;
61    }
62
63    /**
64     * Lock this instance, making it immutable. After an instance is locked,
65     * calling the {@link #set(String, Object)} method will throw an
66     * <code>AssertFailedException</code>.
67     */
68    public void lock() {
69        locked = true;
70    }
71
72    /**
73     * Return true if this object has been locked, false otherwise. See {@link #lock()}.
74     *
75     * @return true if this object has been locked, false otherwise.
76     */
77    public boolean isLocked() {
78        return locked;
79    }
80
81    /**
82     * @return the client host that submitted the command, as an InetAddress
83     */
84    public InetAddress getClientHost() {
85        return clientHost;
86    }
87
88    /**
89     * @return the Command
90     */
91    public Command getCommand() {
92        return command;
93    }
94
95    /**
96     * @return the time that the command was processed; this may differ slightly from when the command was received.
97     */
98    public Date getTime() {
99        // Return a copy of the Date object to preserve immutability
100        return new Date(time.getTime());
101    }
102
103    /**
104     * Store the value for the specified key. If this object already contained a mapping
105     * for this key, the old value is replaced by the specified value. This method throws
106     * an <code>AssertFailedException</code> if this object has been locked. See {@link #lock()}.
107     *
108     * @param key   - the key; must not be null
109     * @param value - the value to store for the specified key
110     * @throws AssertFailedException - if the key is null or this object has been locked.
111     */
112    public void set(String key, Object value) {
113        Assert.notNull(key, "key");
114        Assert.isFalse(locked, "The InvocationRecord is locked!");
115        data.put(key, value);
116    }
117
118    /**
119     * Returns <code>true</code> if this object contains a mapping for the specified key.
120     *
121     * @param key - the key; must not be null
122     * @return <code>true</code> if there is a mapping for the key
123     * @throws AssertFailedException - if the key is null
124     */
125    public boolean containsKey(String key) {
126        Assert.notNull(key, "key");
127        return data.containsKey(key);
128    }
129
130    /**
131     * Returns a Set view of the keys for the data stored in this object.
132     * Changes to the returned Set have no effect on the data stored within this object
133     * .
134     *
135     * @return the Set of keys for the data stored within this object
136     */
137    public Set keySet() {
138        return Collections.unmodifiableSet(data.keySet());
139    }
140
141    /**
142     * Get the String value associated with the specified key. Returns null if there is
143     * no mapping for this key. A return value of null does not necessarily indicate that
144     * this object contains no mapping for the key; it's also possible that the value was
145     * explicitly set to null for the key. The containsKey operation may be used to
146     * distinguish these two cases.
147     *
148     * @param key - the key; must not be null
149     * @return the String data stored at the specified key; may be null
150     * @throws ClassCastException    - if the object for the specified key is not a String
151     * @throws AssertFailedException - if the key is null
152     */
153    public String getString(String key) {
154        Assert.notNull(key, "key");
155        return (String) data.get(key);
156    }
157
158    /**
159     * Get the Object value associated with the specified key. Returns null if there is
160     * no mapping for this key. A return value of null does not necessarily indicate that
161     * this object contains no mapping for the key; it's also possible that the value was
162     * explicitly set to null for the key. The containsKey operation may be used to
163     * distinguish these two cases.
164     *
165     * @param key - the key; must not be null
166     * @return the data stored at the specified key, as an Object; may be null
167     * @throws AssertFailedException - if the key is null
168     */
169    public Object getObject(String key) {
170        Assert.notNull(key, "key");
171        return data.get(key);
172    }
173
174    /**
175     * Return the String representation of this object
176     *
177     * @see java.lang.Object#toString()
178     */
179    public String toString() {
180        return "InvocationRecord[time=" + time + " client-host=" + clientHost + " command=" + command + " data=" + data + "]";
181    }
182}
183