org.osgi.util.mobile
Class UserPromptCondition

java.lang.Object
  org.osgi.util.mobile.UserPromptCondition

All Implemented Interfaces:

Condition

public class UserPromptCondition

extends java.lang.Object

implements Condition

Class representing a user prompt condition. Instances of this class hold two values: a prompt string that is to be displayed to the user and the permission level string according to MIDP2.0 (oneshot, session, blanket).

Field Summary

Fields inherited from interface org.osgi.service.condpermadmin.Condition

FALSE, TRUE

Method Summary

static Condition	getCondition(Bundle bundle, ConditionInfo conditionInfo) Returns a UserPromptCondition object with the given prompt string and permission level.
boolean	isMutable() Checks whether the condition may change during the lifetime of the UserPromptCondition object.
boolean	isPostponed() Checks if the isSatisfied() method needs to prompt the user, thus cannot give results instantly.
boolean	isSatisfied() Displays the prompt string to the user and returns true if the user accepts.
boolean	isSatisfied(Condition[] conds, java.util.Dictionary context) Checks an array of UserPrompt conditions.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

getCondition

public static Condition getCondition(Bundle bundle,
                                     ConditionInfo conditionInfo)

Returns a UserPromptCondition object with the given prompt string and permission level. The user should be given choice as to what level of permission is given. Thus, the lifetime of the permission is controlled by the user.

Parameters:

bundle - the bundle to ask about.

conditionInfo - the conditionInfo containing the construction information. Its ConditionInfo.getArgs() method should return a String array with 4 strings in it:

0. the possible permission levels. This is a comma-separated list that can contain following strings: ONESHOT SESSION BLANKET. The order is not important. This parameter is case-insensitive.
1. the default permission level, one chosen from the possible permission levels. If it is an empty string, then there is no default. This parameter is case-insensitive.
2. the message catalog base name. It will be loaded by a ResourceBundle, or equivalent from an exporting OSGi Bundle. Thus, if the catalogName is "com.provider.messages.userprompt", then there should be an OSGi Bundle exporting the "com.provider.messages" package, and inside it files like "userprompt_en_US.properties".
3. textual description of the condition, to be displayed to the user. If it starts with a '%' sign, then the message is looked up from the catalog specified previously. The key is the rest of the string after the '%' sign.

Returns:

The requested UserPromptCondition.

Throws:

java.lang.IllegalArgumentException - if the parameters are malformed.

java.lang.NullPointerException - if one of the parameters is null.

isPostponed

public boolean isPostponed()

Checks if the isSatisfied() method needs to prompt the user, thus cannot give results instantly. This depends on the permission level given in getCondition(Bundle, ConditionInfo).

• ONESHOT - isPostponed always returns true. The user is prompted for question every time.
• SESSION - isPostponed returns true until the user decides either yes or no for the current session.
• BLANKET - isPostponed returns true until the user decides either always or never.

Regardless of the session level, the user is always given the option to reject the prompt permanently, as if BLANKET/never was chosen. In this case, the question is not postponed anymore, and isSatisfied() returns false.
If the system supports an separately accessible permission management GUI, that may reset the condition to its initial state.

Specified by:

isPostponed in interface Condition

Returns:

True, if user interaction is needed.

isMutable

public boolean isMutable()

Checks whether the condition may change during the lifetime of the UserPromptCondition object. This depends on the permission level given in getCondition(Bundle, ConditionInfo).

• ONESHOT - true
• SESSION - true, if the application model's session lifetime is shorter than the UserPromptCondition object lifetime
• BLANKET - false

If the system supports separately accessible permission management GUI, then this function may also return true for SESSION and BLANKET.

Specified by:

isMutable in interface Condition

Returns:

True, if the condition can change.

isSatisfied

public boolean isSatisfied()

Displays the prompt string to the user and returns true if the user accepts. Depending on the amount of levels the condition is assigned to, the prompt may have multiple accept buttons and one of them can be selected by default (see default level parameter at getCondition(Bundle, ConditionInfo)). It must always be possible for the user to stop further prompting of this question, even with ONESHOT and SESSION levels. In case of BLANKET and SESSION levels, it is possible that the user has already answered the question, in this case there will be no prompting, but immediate return with the previous answer.

Specified by:

isSatisfied in interface Condition

Returns:

True if the user accepts the prompt (or accepts any prompt in case there are multiple permission levels).

isSatisfied

public boolean isSatisfied(Condition[] conds,
                           java.util.Dictionary context)

Checks an array of UserPrompt conditions.

Specified by:

isSatisfied in interface Condition

Parameters:

conds - The array containing the UserPrompt conditions to evaluate.

context - Storage area for evaluation. The ConditionalPermissionAdmin may evaluate a condition several times for one permission check, so this context will be used to store results of ONESHOT questions. This way asking the same question twice in a row can be avoided. If context is null, temporary results will not be stored.

Returns:

True, if all conditions are satisfied.

Throws:

java.lang.NullPointerException - if conds is null.