1 /*
2 Copyright 2007 Ramon Servadei
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 */
16 package fulmine.protocol.wire;
17
18 import fulmine.model.component.IComponent;
19
20 /**
21 * A wire identity is the identity format to use when transmitting an entity
22 * 'on-the-wire' using the fulmine delta (FD) protocol. The key distinction
23 * between the wire identity and the {@link String} identity of an entity is
24 * that the wire identity should be a more compact representation of the
25 * identity for transmission. Whereas the identity of a component might be
26 * 'foo-bar', the wire identity may be an integer 1234. Transmitting the wire
27 * identity as a string (UTF-16) 'foo-bar' could take 10 more bytes versus a
28 * 4-byte integer representation. However, as the FD protocol uses a compacted
29 * integral transmission technique, the cost of transmitting the integer can be
30 * as low as 1 byte.
31 * <p>
32 * There are 2 formats for the wire identity; integer and string. Integer is by
33 * far the most efficient format for the wire identity. A wire identity is
34 * format-aware; it knows if it is an Integer Wire Format (IWF) or String Wire
35 * Format (SWF).
36 * <p>
37 * There are some design situations where it is not possible to use an integer
38 * for the wire identity. In these circumstances, generally, the wire identity
39 * would be the same as the identity. This presents wire transmission
40 * inefficiency but is unavoidable in these cases.
41 *
42 * @see IComponent#getWireIdentity()
43 * @author Ramon Servadei
44 *
45 */
46 public interface IWireIdentity
47 {
48
49 /**
50 * Get the wire identity in its integer form. If the wire identity is not an
51 * integer, this method will generate an exception.
52 *
53 * @see #isIntegerWireFormat()
54 * @return the integer form of this wire identity
55 */
56 int getAsInteger();
57
58 /**
59 * Get the wire identity in its string form. If the wire identity is an
60 * integer, this method will return the integer as a string.
61 *
62 * @see #isIntegerWireFormat()
63 * @return the string form of this wire identity
64 */
65 String getAsString();
66
67 /**
68 * Describes the format of this wire identity.
69 *
70 * @return true if the format is integer
71 */
72 boolean isIntegerWireFormat();
73 }