001: /*
002: *
003: *
004: * Copyright 1990-2007 Sun Microsystems, Inc. All Rights Reserved.
005: * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER
006: *
007: * This program is free software; you can redistribute it and/or
008: * modify it under the terms of the GNU General Public License version
009: * 2 only, as published by the Free Software Foundation.
010: *
011: * This program is distributed in the hope that it will be useful, but
012: * WITHOUT ANY WARRANTY; without even the implied warranty of
013: * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
014: * General Public License version 2 for more details (a copy is
015: * included at /legal/license.txt).
016: *
017: * You should have received a copy of the GNU General Public License
018: * version 2 along with this work; if not, write to the Free Software
019: * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
020: * 02110-1301 USA
021: *
022: * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa
023: * Clara, CA 95054 or visit www.sun.com if you need additional
024: * information or have any questions.
025: */
026:
027: package com.sun.midp.midlet;
028:
029: import com.sun.midp.security.Permissions;
030: import com.sun.midp.security.SecurityToken;
031:
032: /**
033: * Represents a MIDlet suite.
034: */
035: public interface MIDletSuite {
036: /** Suite ID that is never used. */
037: public final static int UNUSED_SUITE_ID = 0;
038:
039: /** Suite ID used for internal midlet suites. */
040: public final static int INTERNAL_SUITE_ID = -1;
041:
042: /** Filename of Manifest inside the application archive. */
043: public static final String JAR_MANIFEST = "META-INF/MANIFEST.MF";
044:
045: /** MIDlet property for the size of the application data. */
046: public static final String DATA_SIZE_PROP = "MIDlet-Data-Size";
047:
048: /** MIDlet property for the size of the application archive. */
049: public static final String JAR_SIZE_PROP = "MIDlet-Jar-Size";
050:
051: /** MIDlet property for the application archive URL. */
052: public static final String JAR_URL_PROP = "MIDlet-Jar-URL";
053:
054: /** MIDlet property for the suite name. */
055: public static final String SUITE_NAME_PROP = "MIDlet-Name";
056:
057: /** MIDlet property for the suite vendor. */
058: public static final String VENDOR_PROP = "MIDlet-Vendor";
059:
060: /** MIDlet property for the suite version. */
061: public static final String VERSION_PROP = "MIDlet-Version";
062:
063: /** MIDlet property for the suite description. */
064: public static final String DESC_PROP = "MIDlet-Description";
065:
066: /** MIDlet property for the microedition configuration. */
067: public static final String CONFIGURATION_PROP = "MicroEdition-Configuration";
068:
069: /** MIDlet property for the profile. */
070: public static final String PROFILE_PROP = "MicroEdition-Profile";
071:
072: /** MIDlet Runtime Execution Environment (MIDP.CLDC by default) */
073: public static final String RUNTIME_EXEC_ENV_PROP = "Runtime-Execution-Environment";
074:
075: /** Default value for the Runtime-Execution-Environment property */
076: public static final String RUNTIME_EXEC_ENV_DEFAULT = "MIDP.CLDC";
077:
078: /** MIDlet property for the required permissions. */
079: public static final String PERMISSIONS_PROP = "MIDlet-Permissions";
080:
081: /** MIDlet property for the optional permissions. */
082: public static final String PERMISSIONS_OPT_PROP = "MIDlet-Permissions-Opt";
083:
084: /**
085: * Get a property of the suite. A property is an attribute from
086: * either the application descriptor or JAR Manifest.
087: *
088: * @param key the name of the property
089: * @return A string with the value of the property.
090: * <code>null</code> is returned if no value is available for
091: * the key.
092: */
093: public String getProperty(String key);
094:
095: /**
096: * Gets push setting for interrupting other MIDlets.
097: * Reuses the Permissions.
098: *
099: * @return push setting for interrupting MIDlets the value
100: * will be permission level from {@link Permissions}
101: */
102: public byte getPushInterruptSetting();
103:
104: /**
105: * Gets push options for this suite.
106: *
107: * @return push options are defined in {@link PushRegistryImpl}
108: */
109: public int getPushOptions();
110:
111: /**
112: * Gets list of permissions for this suite.
113: *
114: * @return array of permissions from {@link Permissions}
115: */
116: public byte[] getPermissions();
117:
118: /**
119: * Replace or add a property to the suite for this run only.
120: *
121: * @param token token with the AMS permission set to allowed,
122: * can be null to use the suite's permission
123: * @param key the name of the property
124: * @param value the value of the property
125: *
126: * @exception SecurityException if the caller's token does not have
127: * internal AMS permission
128: */
129: public void setTempProperty(SecurityToken token, String key,
130: String value);
131:
132: /**
133: * Get the name of a MIDlet to display to the user.
134: *
135: * @param className classname of a MIDlet in the suite
136: *
137: * @return name to display to the user
138: */
139: public String getMIDletName(String className);
140:
141: /**
142: * Check to see the suite has the ALLOW level for specific permission.
143: * This is used for by internal APIs that only provide access to
144: * trusted system applications.
145: * <p>
146: * Only trust this method if the object has been obtained from the
147: * Scheduler of the suite.
148: *
149: * @param permission permission ID from
150: * {@link com.sun.midp.security.Permissions}
151: *
152: * @exception SecurityException if the suite is not
153: * allowed to perform the specified action.
154: */
155: public void checkIfPermissionAllowed(int permission);
156:
157: /**
158: * Check for permission and throw an exception if not allowed.
159: * May block to ask the user a question.
160: *
161: * @param permission ID of the permission to check for,
162: * the ID must be from
163: * {@link com.sun.midp.security.Permissions}
164: * @param resource string to insert into the question, can be null if
165: * no %2 in the question
166: *
167: * @exception SecurityException if the permission is not
168: * allowed by this token
169: * @exception InterruptedException if another thread interrupts the
170: * calling thread while this method is waiting to preempt the
171: * display.
172: */
173: public void checkForPermission(int permission, String resource)
174: throws InterruptedException;
175:
176: /**
177: * Checks for permission and throw an exception if not allowed.
178: * May block to ask the user a question.
179: *
180: * @param permission ID of the permission to check for,
181: * the ID must be from
182: * {@link com.sun.midp.security.Permissions}
183: * @param resource string to insert into the question, can be null if
184: * no %2 in the question
185: * @param extraValue string to insert into the question,
186: * can be null if no %3 in the question
187: *
188: * @exception SecurityException if the permission is not
189: * allowed by this token
190: * @exception InterruptedException if another thread interrupts the
191: * calling thread while this method is waiting to preempt the
192: * display.
193: */
194: public void checkForPermission(int permission, String resource,
195: String extraValue) throws InterruptedException;
196:
197: /**
198: * Get the status of the specified permission.
199: * If no API on the device defines the specific permission
200: * requested then it must be reported as denied.
201: * If the status of the permission is not known because it might
202: * require a user interaction then it should be reported as unknown.
203: *
204: * @param permission to check if denied, allowed, or unknown.
205: * @return 0 if the permission is denied; 1 if the permission is allowed;
206: * -1 if the status is unknown
207: */
208: public int checkPermission(String permission);
209:
210: /**
211: * Gets the unique ID of the suite.
212: *
213: * @return suite ID
214: */
215: public int getID();
216:
217: /**
218: * Ask the user want to interrupt the current MIDlet with
219: * a new MIDlet that has received network data.
220: *
221: * @param connection connection to place in the permission question or
222: * null for alarm
223: *
224: * @return true if the use wants interrupt the current MIDlet, else false
225: */
226: public boolean permissionToInterrupt(String connection);
227:
228: /**
229: * Indicates if the named MIDlet is registered in the suite
230: * with MIDlet-<n> record in the manifest or
231: * application descriptor.
232: * @param midletClassName class name of the MIDlet to be checked
233: *
234: * @return true if the MIDlet is registered
235: */
236: public boolean isRegistered(String midletClassName);
237:
238: /**
239: * Indicates if this suite is trusted.
240: * (not to be confused with a domain named "trusted",
241: * this is used for extra checks beyond permission checking)
242: *
243: * @return true if the suite is trusted false if not
244: */
245: public boolean isTrusted();
246:
247: /**
248: * Check whether the suite classes are preverified and
249: * the suite content hasn't been changed since installation
250: *
251: * @return true if no more verification needed, false otherwise
252: */
253: public boolean isVerified();
254:
255: /**
256: * Determine if the a MIDlet from this suite can be run. Note that
257: * disable suites can still have their settings changed and their
258: * install info displayed.
259: *
260: * @return true if suite is enabled, false otherwise
261: */
262: public boolean isEnabled();
263:
264: /**
265: * Close the opened MIDletSuite
266: */
267: public void close();
268: }
|