1 /*
2 Copyright 2008 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.context;
17
18 import fulmine.model.container.IContainer;
19 import fulmine.model.field.IField;
20
21 /**
22 * Represents the permission profile for the {@link IFulmineContext}.
23 * Permissions govern the visibility of published data by subscribers. A
24 * publisher of data will assign permission rights to its data. Subscribers of
25 * the data must have appropriate permission rights to view the data.
26 * <p>
27 * Permission tokens are attached to {@link IField}s of an {@link IContainer}.
28 * When reading its state from a wire frame, a field will check its permission
29 * token against that of the context. If the permissions 'match' then the field
30 * will read its state from the wire frame and application code will be able to
31 * view the state of the field. If the permission tokens do not match then
32 * application code will have access to the field but its value will be blank
33 * (or null). A similar strategy is applied when a remote context attempts to
34 * update a local container's fields; if the permissions do not match, the
35 * operation is not permitted.
36 * <p>
37 * A permission token for a field is composed of two segments; an application
38 * code and a permission code. This provides the ability for a single
39 * application to expose multiple permissions (e.g. level1, level2 permissions).
40 * The application is essentially hosted by the context and the fields published
41 * by the application will be tagged with a permission token. A subscribing
42 * application (hosted by another context) may have many permission tokens that
43 * allow it to view the fields of many other applications.
44 * <p>
45 * The definition of a permission match is performed by implementations of this
46 * interface.
47 *
48 * @author Ramon Servadei
49 */
50 public interface IPermissionProfile
51 {
52 /** Represents a default application */
53 byte DEFAULT_APPLICATION = (byte) 0x0;
54
55 /** Represents the default permission code */
56 short DEFAULT_PERMISSION = (short) 0x0;
57
58 /**
59 * Determine if the application and permission arguments are contained by
60 * this permission profile.
61 * <p>
62 * This is generally used when reading the wire-state of an {@link IField}
63 * and determines if the data is de-serialised into the remote instance;
64 * basically prevents data from being read in a context that does not have
65 * permission to do so.
66 *
67 * @param application
68 * the application code
69 * @param permission
70 * the permission code
71 * @return <code>true</code> if the application and permission codes are
72 * contained by (matched by) this profile, <code>false</code>
73 * otherwise
74 */
75 boolean contains(byte application, short permission);
76
77 /**
78 * Determine if the received application and permission codes are matched
79 * with a set of application and permission codes.
80 * <p>
81 * This is generally used when handling RPC operations received from a
82 * remote context to update a local container. The permission attributes of
83 * the remote context need to be compared with those of the target
84 * {@link IField} in the local container to determine if the operation
85 * should proceed.
86 *
87 * @see IRemoteUpdateHandler
88 *
89 * @param receivedApplication
90 * the received application code (generally the application code
91 * of a remote context)
92 * @param receivedPermission
93 * the received permission code (generally the permission code of
94 * a remote context)
95 * @param matchWithApplication
96 * the application code to match with the received one (generally
97 * the application code of the field being updated)
98 * @param matchWithPermission
99 * the permission code to match with the received one (generally
100 * the permission code of the field being updated)
101 * @return <code>true</code> if the received application and permission
102 * codes are matched by the application and permission codes to
103 * compare with, <code>false</code> otherwise
104 */
105 boolean matches(byte receivedApplication, short receivedPermission,
106 byte matchWithApplication, short matchWithPermission);
107
108 /**
109 * Get the application code of this profile
110 *
111 * @return the application code of this profile
112 */
113 byte getApplicationCode();
114
115 /**
116 * Get the permission code of this profile
117 *
118 * @return the permission code of this profile
119 */
120 short getPermissionCode();
121 }