'. '

Privileged API

From APIDesign

(Difference between revisions)
Jump to: navigation, search
(New page: When designing a library and its API, you often do not talk only to one audience of users, but to multiple groups. For example one group shall be allowed to create objects, other group...)
Line 1: Line 1:
When designing a library and its [[API]], you often do not talk only to one audience of users, but to multiple groups. For example one group shall be allowed to create objects, other group shall just query their state. In some sense the first group has more privileges, just like a server administrator can change content of a website, while regular uses can only view its [[HTML]] pages.
When designing a library and its [[API]], you often do not talk only to one audience of users, but to multiple groups. For example one group shall be allowed to create objects, other group shall just query their state. In some sense the first group has more privileges, just like a server administrator can change content of a website, while regular uses can only view its [[HTML]] pages.
-
This topic has been deeply discussed in section ''Give the Creator of an Object More Rights'' in [[Chapter 5]]. You can also listen to [[API Design Tips]] podcast dedicated to [[Privileged API]]: [[Image:Apitip03-constructor-and-competition.mp3]]
+
This topic has been deeply discussed in section ''Give the Creator of an Object More Rights'' in [[Chapter 5]]. You can also listen to [[API Design Tips]] podcast dedicated to [[Privileged API]]: [[Image:Apitip03-constructor-and-competition.mp3]], [[Media:Apitip03-constructor-and-competition.mp3|download]].
 +
== Use Constructor or [[Factory]] Methods ==
 +
The basic trick to achieve privileged mode is to force initialization of certain attributes of an object only during its creation and prevent changing them later. As an example consider a simple lock implementation:
 +
<source lang="java" snippet="mutex.api"/>
 +
The ''readAccess'' method takes a ''Runnable'' which ensures that everyone who acquires the lock also releases it. This is more suitable method for public consumption in [[Cluelessness]] mode then pair of ''lock''/''unlock'' methods. One just cannot forget to ''unlock'':
 +
 +
<source lang="java" snippet="mutex.use"/>
 +
 +
However (and we found that in [[NetBeans]] [[API]]s), when used frequently there may be too many temporary ''Runnable'' objects being created. This may hurt performance and as such one may want the ''lock''/''unlock'' pair of methods to be available to those who can be trusted to use it correctly. This can be done with following addition to the [[API]]:
 +
 +
<source lang="java" snippet="mutex.privileged.api"/>
 +
 +
The ''Privileged'' class then serves as a handle which the creator of the ''Mutex'' instance may keep reference to:
 +
 +
<source lang="java" snippet="mutex.init"/>
 +
 +
and use it for privileged access, while everyone else keeps access to the safe ''Mutex'' method. So creator can call:
 +
 +
<source lang="java" snippet="mutex.privileged"/>
 +
 +
Regular users have to rely on old good ''readAccess''. This is one way to create [[API]] for privileged use. There are other as discussed in [[Chapter 5]].
 +
 +
<comments/>
[[Category:APIDesignPatterns]] [[Category:APIDesignPatterns:Creational]]
[[Category:APIDesignPatterns]] [[Category:APIDesignPatterns:Creational]]

Revision as of 17:00, 25 May 2009

When designing a library and its API, you often do not talk only to one audience of users, but to multiple groups. For example one group shall be allowed to create objects, other group shall just query their state. In some sense the first group has more privileges, just like a server administrator can change content of a website, while regular uses can only view its HTML pages.

This topic has been deeply discussed in section Give the Creator of an Object More Rights in Chapter 5. You can also listen to API Design Tips podcast dedicated to Privileged API: , download.

Use Constructor or Factory Methods

The basic trick to achieve privileged mode is to force initialization of certain attributes of an object only during its creation and prevent changing them later. As an example consider a simple lock implementation:

Code from Mutex.java:
See the whole file.

public final class Mutex {
    Lock lock = new ReentrantLock();
 
    public Mutex() {
    }
 
    public void withLock(Runnable r) {
        try {
            lock.lock();
            r.run();
        } finally {
            lock.unlock();
        }
    }
}
 

The readAccess method takes a Runnable which ensures that everyone who acquires the lock also releases it. This is more suitable method for public consumption in Cluelessness mode then pair of lock/unlock methods. One just cannot forget to unlock:

Code from MutexTest.java:
See the whole file.

class R implements Runnable {
    int cnt;
 
    public void run() {
        cnt++;
    }
}
R r = new R();
MUTEX.withLock(r);
assertEquals("Counter increased", 1, r.cnt);
 

However (and we found that in NetBeans APIs), when used frequently there may be too many temporary Runnable objects being created. This may hurt performance and as such one may want the lock/unlock pair of methods to be available to those who can be trusted to use it correctly. This can be done with following addition to the API:

Code from Mutex.java:
See the whole file.

public Mutex(Privileged privileged) {
    if (privileged.mutex != null) {
        throw new IllegalStateException();
    }
    privileged.mutex = this;
}
 
public static final class Privileged {
    private Mutex mutex;
 
    public void lock() {
        mutex.lock.lock();
    }
 
    public void unlock() {
        mutex.lock.unlock();
    }
}
 

The Privileged class then serves as a handle which the creator of the Mutex instance may keep reference to:

Code from MutexTest.java:
See the whole file.

private static final Mutex.Privileged PRIVILEGED = new Mutex.Privileged();
public static final Mutex MUTEX = new Mutex(PRIVILEGED);
 

and use it for privileged access, while everyone else keeps access to the safe Mutex method. So creator can call:

Code from MutexTest.java:
See the whole file.

try {
    PRIVILEGED.lock();
    // do the operation
    cnt++;
} finally {
   PRIVILEGED.unlock();
}
assertEquals("Counter increased", 1, cnt);
 

Regular users have to rely on old good readAccess. This is one way to create API for privileged use. There are other as discussed in Chapter 5.

<comments/>

Personal tools
buy