http://wiki.apidesign.org/index.php?title=Privileged_API&feed=atom&action=historyPrivileged API - Revision history2024-03-29T13:30:02ZRevision history for this page on the wikiMediaWiki 1.12.0rc1http://wiki.apidesign.org/index.php?title=Privileged_API&diff=2464&oldid=prevJaroslavTulach at 07:38, 26 May 20092009-05-26T07:38:43Z<p></p>
<table style="background-color: white; color:black;">
<col class='diff-marker' />
<col class='diff-content' />
<col class='diff-marker' />
<col class='diff-content' />
<tr>
<td colspan='2' style="background-color: white; color:black;">←Older revision</td>
<td colspan='2' style="background-color: white; color:black;">Revision as of 07:38, 26 May 2009</td>
</tr>
<tr><td colspan="2" class="diff-lineno">Line 9:</td>
<td colspan="2" class="diff-lineno">Line 9:</td></tr>
<tr><td class='diff-marker'> </td><td style="background: #eee; color:black; font-size: smaller;"><div><source lang="java" snippet="mutex.api"/></div></td><td class='diff-marker'> </td><td style="background: #eee; color:black; font-size: smaller;"><div><source lang="java" snippet="mutex.api"/></div></td></tr>
<tr><td class='diff-marker'> </td><td style="background: #eee; color:black; font-size: smaller;"></td><td class='diff-marker'> </td><td style="background: #eee; color:black; font-size: smaller;"></td></tr>
<tr><td class='diff-marker'>-</td><td style="background: #ffa; color:black; font-size: smaller;"><div>The ''<del style="color: red; font-weight: bold; text-decoration: none;">readAccess</del>'' 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'':</div></td><td class='diff-marker'>+</td><td style="background: #cfc; color:black; font-size: smaller;"><div>The ''<ins style="color: red; font-weight: bold; text-decoration: none;">withLock</ins>'' 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'':</div></td></tr>
<tr><td class='diff-marker'> </td><td style="background: #eee; color:black; font-size: smaller;"></td><td class='diff-marker'> </td><td style="background: #eee; color:black; font-size: smaller;"></td></tr>
<tr><td class='diff-marker'> </td><td style="background: #eee; color:black; font-size: smaller;"><div><source lang="java" snippet="mutex.use"/></div></td><td class='diff-marker'> </td><td style="background: #eee; color:black; font-size: smaller;"><div><source lang="java" snippet="mutex.use"/></div></td></tr>
<tr><td colspan="2" class="diff-lineno">Line 17:</td>
<td colspan="2" class="diff-lineno">Line 17:</td></tr>
<tr><td class='diff-marker'> </td><td style="background: #eee; color:black; font-size: smaller;"><div><source lang="java" snippet="mutex.privileged.api"/></div></td><td class='diff-marker'> </td><td style="background: #eee; color:black; font-size: smaller;"><div><source lang="java" snippet="mutex.privileged.api"/></div></td></tr>
<tr><td class='diff-marker'> </td><td style="background: #eee; color:black; font-size: smaller;"></td><td class='diff-marker'> </td><td style="background: #eee; color:black; font-size: smaller;"></td></tr>
<tr><td class='diff-marker'>-</td><td style="background: #ffa; color:black; font-size: smaller;"><div>The ''Privileged'' class then serves as a handle which the creator of the ''Mutex'' instance may keep reference to:</div></td><td class='diff-marker'>+</td><td style="background: #cfc; color:black; font-size: smaller;"><div>The ''Privileged'' class then serves as a handle which the creator of the ''Mutex'' instance may keep <ins style="color: red; font-weight: bold; text-decoration: none;">(private) </ins>reference to:</div></td></tr>
<tr><td class='diff-marker'> </td><td style="background: #eee; color:black; font-size: smaller;"></td><td class='diff-marker'> </td><td style="background: #eee; color:black; font-size: smaller;"></td></tr>
<tr><td class='diff-marker'> </td><td style="background: #eee; color:black; font-size: smaller;"><div><source lang="java" snippet="mutex.init"/></div></td><td class='diff-marker'> </td><td style="background: #eee; color:black; font-size: smaller;"><div><source lang="java" snippet="mutex.init"/></div></td></tr>
<tr><td class='diff-marker'> </td><td style="background: #eee; color:black; font-size: smaller;"></td><td class='diff-marker'> </td><td style="background: #eee; color:black; font-size: smaller;"></td></tr>
<tr><td class='diff-marker'>-</td><td style="background: #ffa; color:black; font-size: smaller;"><div>and use it for privileged access, while everyone else <del style="color: red; font-weight: bold; text-decoration: none;">keeps </del>access <del style="color: red; font-weight: bold; text-decoration: none;">to </del>the safe ''Mutex'' <del style="color: red; font-weight: bold; text-decoration: none;">method</del>. So creator can call:</div></td><td class='diff-marker'>+</td><td style="background: #cfc; color:black; font-size: smaller;"><div>and use it for privileged access <ins style="color: red; font-weight: bold; text-decoration: none;">(as the field is not accessible to public use)</ins>, while everyone else <ins style="color: red; font-weight: bold; text-decoration: none;">can </ins>access <ins style="color: red; font-weight: bold; text-decoration: none;">only </ins>the safe <ins style="color: red; font-weight: bold; text-decoration: none;">methods (as the </ins>''Mutex'' <ins style="color: red; font-weight: bold; text-decoration: none;">field is publicly exposed in the [[API]])</ins>. So creator can call:</div></td></tr>
<tr><td class='diff-marker'> </td><td style="background: #eee; color:black; font-size: smaller;"></td><td class='diff-marker'> </td><td style="background: #eee; color:black; font-size: smaller;"></td></tr>
<tr><td class='diff-marker'> </td><td style="background: #eee; color:black; font-size: smaller;"><div><source lang="java" snippet="mutex.privileged"/></div></td><td class='diff-marker'> </td><td style="background: #eee; color:black; font-size: smaller;"><div><source lang="java" snippet="mutex.privileged"/></div></td></tr>
<tr><td class='diff-marker'> </td><td style="background: #eee; color:black; font-size: smaller;"></td><td class='diff-marker'> </td><td style="background: #eee; color:black; font-size: smaller;"></td></tr>
<tr><td class='diff-marker'>-</td><td style="background: #ffa; color:black; font-size: smaller;"><div>Regular users have to rely on old good ''<del style="color: red; font-weight: bold; text-decoration: none;">readAccess</del>''. This is one way to create [[API]] for privileged use. There are other as discussed in [[Chapter 5]].</div></td><td class='diff-marker'>+</td><td style="background: #cfc; color:black; font-size: smaller;"><div>Regular users have to rely on old good <ins style="color: red; font-weight: bold; text-decoration: none;">and safe </ins>''<ins style="color: red; font-weight: bold; text-decoration: none;">withLock</ins>''. </div></td></tr>
<tr><td colspan="2"> </td><td class='diff-marker'>+</td><td style="background: #cfc; color:black; font-size: smaller;"><div> </div></td></tr>
<tr><td colspan="2"> </td><td class='diff-marker'>+</td><td style="background: #cfc; color:black; font-size: smaller;"><div><ins style="color: red; font-weight: bold; text-decoration: none;">=== Everyone Can Become Privileged ===</ins></div></td></tr>
<tr><td colspan="2"> </td><td class='diff-marker'>+</td><td style="background: #cfc; color:black; font-size: smaller;"><div> </div></td></tr>
<tr><td colspan="2"> </td><td class='diff-marker'>+</td><td style="background: #cfc; color:black; font-size: smaller;"><div><ins style="color: red; font-weight: bold; text-decoration: none;">Please note that the author of a [[Privileged API]] does not assign roles to users of own [[API]] in advance. There are no ultimately ''privileged'' users knowing some special ''token'' to use the library in special mode. There are no library ''adminstrators'' that could log into a web server and manage its [[HTML]] pages. Initially, when approaching a [[Privileged API]] everyone is treated equally. Everyone can create anything. However those who create an object of such [[API]] can become ''privileged'' gaining special access to that object instance (but not to other instances).</ins></div></td></tr>
<tr><td colspan="2"> </td><td class='diff-marker'>+</td><td style="background: #cfc; color:black; font-size: smaller;"><div> </div></td></tr>
<tr><td colspan="2"> </td><td class='diff-marker'>+</td><td style="background: #cfc; color:black; font-size: smaller;"><div><ins style="color: red; font-weight: bold; text-decoration: none;">In the context of previous ''Mutex'' example it means that everyone can create new instance of ''Mutex'' (using the privileged constructor) and re-expose such instance in own [[API]]. However by keeping the ''Privileged'' instance private, the right to act as privileged user with respect to the one instance of the ''Mutex'' remains restricted to its creator (plus those who are given the ''Privileged'' instance as a shared token by some side-ways).</ins></div></td></tr>
<tr><td colspan="2"> </td><td class='diff-marker'>+</td><td style="background: #cfc; color:black; font-size: smaller;"><div> </div></td></tr>
<tr><td colspan="2"> </td><td class='diff-marker'>+</td><td style="background: #cfc; color:black; font-size: smaller;"><div>This is one way to create [[API]] for privileged use. There are other as discussed in [[Chapter 5]].</div></td></tr>
<tr><td class='diff-marker'> </td><td style="background: #eee; color:black; font-size: smaller;"></td><td class='diff-marker'> </td><td style="background: #eee; color:black; font-size: smaller;"></td></tr>
<tr><td class='diff-marker'> </td><td style="background: #eee; color:black; font-size: smaller;"><div><comments/></div></td><td class='diff-marker'> </td><td style="background: #eee; color:black; font-size: smaller;"><div><comments/></div></td></tr>
<tr><td class='diff-marker'> </td><td style="background: #eee; color:black; font-size: smaller;"></td><td class='diff-marker'> </td><td style="background: #eee; color:black; font-size: smaller;"></td></tr>
<tr><td class='diff-marker'> </td><td style="background: #eee; color:black; font-size: smaller;"><div>[[Category:APIDesignPatterns]] [[Category:APIDesignPatterns:Creational]]</div></td><td class='diff-marker'> </td><td style="background: #eee; color:black; font-size: smaller;"><div>[[Category:APIDesignPatterns]] [[Category:APIDesignPatterns:Creational]]</div></td></tr>
</table>JaroslavTulachhttp://wiki.apidesign.org/index.php?title=Privileged_API&diff=2461&oldid=prevJaroslavTulach at 17:00, 25 May 20092009-05-25T17:00:10Z<p></p>
<table style="background-color: white; color:black;">
<col class='diff-marker' />
<col class='diff-content' />
<col class='diff-marker' />
<col class='diff-content' />
<tr>
<td colspan='2' style="background-color: white; color:black;">←Older revision</td>
<td colspan='2' style="background-color: white; color:black;">Revision as of 17:00, 25 May 2009</td>
</tr>
<tr><td colspan="2" class="diff-lineno">Line 1:</td>
<td colspan="2" class="diff-lineno">Line 1:</td></tr>
<tr><td class='diff-marker'> </td><td style="background: #eee; color:black; font-size: smaller;"><div>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.</div></td><td class='diff-marker'> </td><td style="background: #eee; color:black; font-size: smaller;"><div>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.</div></td></tr>
<tr><td class='diff-marker'> </td><td style="background: #eee; color:black; font-size: smaller;"></td><td class='diff-marker'> </td><td style="background: #eee; color:black; font-size: smaller;"></td></tr>
<tr><td class='diff-marker'>-</td><td style="background: #ffa; color:black; font-size: smaller;"><div>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]]</div></td><td class='diff-marker'>+</td><td style="background: #cfc; color:black; font-size: smaller;"><div>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]]<ins style="color: red; font-weight: bold; text-decoration: none;">, [[Media:Apitip03-constructor-and-competition.mp3|download]].</ins></div></td></tr>
<tr><td class='diff-marker'> </td><td style="background: #eee; color:black; font-size: smaller;"></td><td class='diff-marker'> </td><td style="background: #eee; color:black; font-size: smaller;"></td></tr>
<tr><td colspan="2"> </td><td class='diff-marker'>+</td><td style="background: #cfc; color:black; font-size: smaller;"><div><ins style="color: red; font-weight: bold; text-decoration: none;">== Use Constructor or [[Factory]] Methods ==</ins></div></td></tr>
<tr><td class='diff-marker'> </td><td style="background: #eee; color:black; font-size: smaller;"></td><td class='diff-marker'> </td><td style="background: #eee; color:black; font-size: smaller;"></td></tr>
<tr><td colspan="2"> </td><td class='diff-marker'>+</td><td style="background: #cfc; color:black; font-size: smaller;"><div><ins style="color: red; font-weight: bold; text-decoration: none;">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:</ins></div></td></tr>
<tr><td class='diff-marker'> </td><td style="background: #eee; color:black; font-size: smaller;"></td><td class='diff-marker'> </td><td style="background: #eee; color:black; font-size: smaller;"></td></tr>
<tr><td colspan="2"> </td><td class='diff-marker'>+</td><td style="background: #cfc; color:black; font-size: smaller;"><div><ins style="color: red; font-weight: bold; text-decoration: none;"><source lang="java" snippet="mutex.api"/></ins></div></td></tr>
<tr><td class='diff-marker'> </td><td style="background: #eee; color:black; font-size: smaller;"></td><td class='diff-marker'> </td><td style="background: #eee; color:black; font-size: smaller;"></td></tr>
<tr><td colspan="2"> </td><td class='diff-marker'>+</td><td style="background: #cfc; color:black; font-size: smaller;"><div><ins style="color: red; font-weight: bold; text-decoration: none;">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'':</ins></div></td></tr>
<tr><td colspan="2"> </td><td class='diff-marker'>+</td><td style="background: #cfc; color:black; font-size: smaller;"><div><ins style="color: red; font-weight: bold; text-decoration: none;"></ins></div></td></tr>
<tr><td colspan="2"> </td><td class='diff-marker'>+</td><td style="background: #cfc; color:black; font-size: smaller;"><div><ins style="color: red; font-weight: bold; text-decoration: none;"><source lang="java" snippet="mutex.use"/></ins></div></td></tr>
<tr><td colspan="2"> </td><td class='diff-marker'>+</td><td style="background: #cfc; color:black; font-size: smaller;"><div><ins style="color: red; font-weight: bold; text-decoration: none;"></ins></div></td></tr>
<tr><td colspan="2"> </td><td class='diff-marker'>+</td><td style="background: #cfc; color:black; font-size: smaller;"><div><ins style="color: red; font-weight: bold; text-decoration: none;">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]]:</ins></div></td></tr>
<tr><td colspan="2"> </td><td class='diff-marker'>+</td><td style="background: #cfc; color:black; font-size: smaller;"><div><ins style="color: red; font-weight: bold; text-decoration: none;"></ins></div></td></tr>
<tr><td colspan="2"> </td><td class='diff-marker'>+</td><td style="background: #cfc; color:black; font-size: smaller;"><div><ins style="color: red; font-weight: bold; text-decoration: none;"><source lang="java" snippet="mutex.privileged.api"/></ins></div></td></tr>
<tr><td colspan="2"> </td><td class='diff-marker'>+</td><td style="background: #cfc; color:black; font-size: smaller;"><div><ins style="color: red; font-weight: bold; text-decoration: none;"></ins></div></td></tr>
<tr><td colspan="2"> </td><td class='diff-marker'>+</td><td style="background: #cfc; color:black; font-size: smaller;"><div><ins style="color: red; font-weight: bold; text-decoration: none;">The ''Privileged'' class then serves as a handle which the creator of the ''Mutex'' instance may keep reference to:</ins></div></td></tr>
<tr><td colspan="2"> </td><td class='diff-marker'>+</td><td style="background: #cfc; color:black; font-size: smaller;"><div><ins style="color: red; font-weight: bold; text-decoration: none;"></ins></div></td></tr>
<tr><td colspan="2"> </td><td class='diff-marker'>+</td><td style="background: #cfc; color:black; font-size: smaller;"><div><ins style="color: red; font-weight: bold; text-decoration: none;"><source lang="java" snippet="mutex.init"/></ins></div></td></tr>
<tr><td colspan="2"> </td><td class='diff-marker'>+</td><td style="background: #cfc; color:black; font-size: smaller;"><div><ins style="color: red; font-weight: bold; text-decoration: none;"></ins></div></td></tr>
<tr><td colspan="2"> </td><td class='diff-marker'>+</td><td style="background: #cfc; color:black; font-size: smaller;"><div><ins style="color: red; font-weight: bold; text-decoration: none;">and use it for privileged access, while everyone else keeps access to the safe ''Mutex'' method. So creator can call:</ins></div></td></tr>
<tr><td colspan="2"> </td><td class='diff-marker'>+</td><td style="background: #cfc; color:black; font-size: smaller;"><div><ins style="color: red; font-weight: bold; text-decoration: none;"></ins></div></td></tr>
<tr><td colspan="2"> </td><td class='diff-marker'>+</td><td style="background: #cfc; color:black; font-size: smaller;"><div><ins style="color: red; font-weight: bold; text-decoration: none;"><source lang="java" snippet="mutex.privileged"/></ins></div></td></tr>
<tr><td colspan="2"> </td><td class='diff-marker'>+</td><td style="background: #cfc; color:black; font-size: smaller;"><div><ins style="color: red; font-weight: bold; text-decoration: none;"></ins></div></td></tr>
<tr><td colspan="2"> </td><td class='diff-marker'>+</td><td style="background: #cfc; color:black; font-size: smaller;"><div><ins style="color: red; font-weight: bold; text-decoration: none;">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]].</ins></div></td></tr>
<tr><td colspan="2"> </td><td class='diff-marker'>+</td><td style="background: #cfc; color:black; font-size: smaller;"><div><ins style="color: red; font-weight: bold; text-decoration: none;"></ins></div></td></tr>
<tr><td colspan="2"> </td><td class='diff-marker'>+</td><td style="background: #cfc; color:black; font-size: smaller;"><div><ins style="color: red; font-weight: bold; text-decoration: none;"><comments/></ins></div></td></tr>
<tr><td class='diff-marker'> </td><td style="background: #eee; color:black; font-size: smaller;"></td><td class='diff-marker'> </td><td style="background: #eee; color:black; font-size: smaller;"></td></tr>
<tr><td class='diff-marker'> </td><td style="background: #eee; color:black; font-size: smaller;"><div>[[Category:APIDesignPatterns]] [[Category:APIDesignPatterns:Creational]]</div></td><td class='diff-marker'> </td><td style="background: #eee; color:black; font-size: smaller;"><div>[[Category:APIDesignPatterns]] [[Category:APIDesignPatterns:Creational]]</div></td></tr>
</table>JaroslavTulachhttp://wiki.apidesign.org/index.php?title=Privileged_API&diff=2459&oldid=prevJaroslavTulach: 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...2009-05-25T16:17:06Z<p>New page: When designing a library and its <a href="/wiki/API" class="mw-redirect" title="API">API</a>, 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...</p>
<p><b>New page</b></p><div>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.<br />
<br />
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]]<br />
<br />
<br />
<br />
<br />
<br />
[[Category:APIDesignPatterns]] [[Category:APIDesignPatterns:Creational]]</div>JaroslavTulach