update javadocs and pom.xml (#158)

* update package gourpid and javadocs

* update readme

* update readme

README.md

@@ -5,7 +5,24 @@ For complete documentation and detailed examples visit the Wiki.
 
 ## Installation
 
-### Install using Maven
+### Install to maven local
+```
+git clone https://github.com/usnistgov/policy-machine-core.git
+
+cd policy-machine-core
+
+mvn clean install
+```
+
+```
+<dependency>
+    <groupId>gov.nist.csd.pm</groupId>
+    <artifactId>policy-machine-core</artifactId>
+    <version>3.0.0</version>
+</dependency>
+```
+
+### Install using Jitpack
 Policy Machine Core uses [JitPack](https://jitpack.io/) to compile and build the artifact to import with maven.
 
 First, add jitpack as a repository

pom.xml

@@ -4,7 +4,7 @@
          xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
     <modelVersion>4.0.0</modelVersion>
 
-    <groupId>com.github.PM-Master</groupId>
+    <groupId>gov.nist.csd.pm</groupId>
     <artifactId>policy-machine-core</artifactId>
     <packaging>jar</packaging>
     <version>3.0.0</version>

src/main/java/gov/nist/csd/pm/impl/memory/pap/MemoryAccessQuerier.java

@@ -173,7 +173,7 @@ public Explain explain(UserContext userCtx, String target) throws PMException {
     }
 
     @Override
-    public Set<String> computePersonalObjectSystem(UserContext userCtx) throws PMException {
+    public Collection<String> computePersonalObjectSystem(UserContext userCtx) throws PMException {
         // Prepare the hashset to return.
         HashSet<String> hsOa = new HashSet<>();
 

src/main/java/gov/nist/csd/pm/pap/PolicyPoint.java

@@ -44,9 +44,7 @@ public interface PolicyPoint extends Transactional {
     /**
      * Deserialize the given input string into the current policy state. The user defined in the UserContext needs to exist
      * in the graph created if any obligations are created. If the user does not exist before an obligation is created
-     * an exception will be thrown. This method also resets the policy before deserialization. However, the {@link AdminPolicy}
-     * nodes are assumed to be created and can be referenced in the input string without explicit creation. If any of the
-     * admin policy nodes are created in the input string an exception will be thrown.
+     * an exception will be thrown.
      *
      * @param author The UserContext describing the author of the deserialized policy elements.
      * @param input The string representation of the policy to deserialize.

src/main/java/gov/nist/csd/pm/pap/modification/PolicyModification.java

@@ -6,31 +6,26 @@
 public interface PolicyModification {
 
     /**
-     * Get the graph component of the policy.
      * @return The GraphModification implementation.
      */
     GraphModification graph();
 
     /**
-     * Get the prohibitions component of the policy.
      * @return The ProhibitionsModification implementation.
      */
     ProhibitionsModification prohibitions();
 
     /**
-     * Get the obligations component of the policy.
      * @return The ObligationsModification implementation.
      */
     ObligationsModification obligations();
 
     /**
-     * Get the operations component of the policy.
      * @return The ObligationsModification implementation.
      */
     OperationsModification operations();
 
     /**
-     * Get the routines component of the policy.
      * @return The RoutinesModification implementation.
      */
     RoutinesModification routines();

src/main/java/gov/nist/csd/pm/pap/query/AccessQuery.java

@@ -6,20 +6,108 @@
 
 import java.util.Collection;
 import java.util.Map;
-import java.util.Set;
 
+/**
+ * Interface to query the access state of the policy.
+ */
 public interface AccessQuery {
 
+    /**
+     * Compute the privileges the user has on the target node.
+     * @param userCtx The user and process (optional).
+     * @param target The target node.
+     * @return An AccessRightSet that contains the users privileges on the target node.
+     * @throws PMException If there is an error in the PM.
+     */
     AccessRightSet computePrivileges(UserContext userCtx, String target) throws PMException;
+
+    /**
+     * Compute the privileges that are denied for the user on the target node.
+     * @param userCtx The user and process (optional).
+     * @param target The target node.
+     * @return An AccessRightSet that contains the users denied privileges on the target node.
+     * @throws PMException If there is an error in the PM.
+     */
     AccessRightSet computeDeniedPrivileges(UserContext userCtx, String target) throws PMException;
-    Map<String, AccessRightSet> computePolicyClassAccessRights(UserContext userContext, String target) throws PMException;
+
+    /**
+     * Compute the access rights that a user has access to under each policy class the target is an ascendant of. This
+     * does not include prohibitions.
+     * @param userCtx The user and process (optional).
+     * @param target The target node.
+     * @return A mapping of policy class names to the access rights the user has under them on the target node.
+     * @throws PMException If there is an error in the PM.
+     */
+    Map<String, AccessRightSet> computePolicyClassAccessRights(UserContext userCtx, String target) throws PMException;
+
+    /**
+     * Compute a mapping of all the nodes the user has access to the access rights they have on each.
+     * @param userCtx The user and process (optional).
+     * @return A mapping of node names to access rights.
+     * @throws PMException If there is an error in the PM.
+     */
     Map<String, AccessRightSet> computeCapabilityList(UserContext userCtx) throws PMException;
+
+    /**
+     * Compute the Access Control List for the given target.
+     * @param target The target node.
+     * @return A mapping of each user and their privileges on the target.
+     * @throws PMException If there is an error in the PM.
+     */
     Map<String, AccessRightSet> computeACL(String target) throws PMException;
+
+    /**
+     * Compute the attributes that are targets of associations in which the user attribute is a descendant of the user.
+     * @param user The user node.
+     * @return A mapping of the destination attributes to the access rights in the destination association.
+     * @throws PMException If there is an error in the PM.
+     */
     Map<String, AccessRightSet> computeDestinationAttributes(String user) throws PMException;
+
+    /**
+     * Compute the privileges for all ascendants of a given root node.
+     * @param userCtx The user and process (optional).
+     * @param root The root node.
+     * @return A mapping of ascendant nodes to the privileges of the user.
+     * @throws PMException If there is an error in the PM.
+     */
     Map<String, AccessRightSet> computeAscendantPrivileges(UserContext userCtx, String root) throws PMException;
+
+    /**
+     * Explain why a user may or may not have privileges on a target node.
+     * @param userCtx The user and process (optional).
+     * @param target The target node.
+     * @return An Explain object which enumerates the paths under each policy class that the user has access to the
+     *         target node.
+     * @throws PMException If there is an error in the PM.
+     */
     Explain explain(UserContext userCtx, String target) throws PMException;
-    Set<String> computePersonalObjectSystem(UserContext userCtx) throws PMException;
+
+    /**
+     * Compute the original configuration of a user's POS.
+     *
+     * @param userCtx The user and process (optional).
+     * @return A set of nodes representing the first level of the user's POS.
+     * @throws PMException If there is an error in the PM.
+     */
+    Collection<String> computePersonalObjectSystem(UserContext userCtx) throws PMException;
+
+    /**
+     * Compute the ascendants of the root node that the user has at least one access right on.
+     * @param userCtx The user and process (optional).
+     * @param root The root node.
+     * @return The set of nodes that are ascendants of the root node and accessible by the user.
+     * @throws PMException If there is an error in the PM.
+     */
     Collection<String> computeAccessibleAscendants(UserContext userCtx, String root) throws PMException;
+
+    /**
+     * Compute the descendants of the root node that the user has at least one access right on.
+     * @param userCtx The user and process (optional).
+     * @param root The root node.
+     * @return The set of nodes that are descendants of the root node and accessible by the user.
+     * @throws PMException If there is an error in the PM.
+     */
     Collection<String> computeAccessibleDescendants(UserContext userCtx, String root) throws PMException;
 
 }

src/main/java/gov/nist/csd/pm/pap/query/GraphQuery.java

@@ -8,6 +8,9 @@
 import java.util.Collection;
 import java.util.Map;
 
+/**
+ * Interface to query the graph.
+ */
 public interface GraphQuery {
 
     /**

src/main/java/gov/nist/csd/pm/pap/query/ObligationsQuery.java

@@ -5,6 +5,9 @@
 
 import java.util.Collection;
 
+/**
+ * Interface to query obligations.
+ */
 public interface ObligationsQuery {
 
     /**

src/main/java/gov/nist/csd/pm/pap/query/OperationsQuery.java

@@ -6,10 +6,31 @@
 
 import java.util.Collection;
 
+/**
+ * Interface to query operations.
+ */
 public interface OperationsQuery {
 
+    /**
+     * Get the resource operations that have been set for the policy.
+     * @return An AccessRightSet containing the resource operations.
+     * @throws PMException If there is an error in the PM.
+     */
     AccessRightSet getResourceOperations() throws PMException;
+
+    /**
+     * Get the names of all admin operations.
+     * @return A collection of all the admin operation names.
+     * @throws PMException If there is an error in the PM.
+     */
     Collection<String> getAdminOperationNames() throws PMException;
+
+    /**
+     * Get the admin operation with the given name.
+     * @param operationName The operation name.
+     * @return The Operation object.
+     * @throws PMException If there is an error in the PM.
+     */
     Operation<?> getAdminOperation(String operationName) throws PMException;
 
 }

src/main/java/gov/nist/csd/pm/pap/query/PolicyQuery.java

@@ -1,11 +1,37 @@
 package gov.nist.csd.pm.pap.query;
 
+/**
+ * Interface for the querying of policy data and access controls state.
+ */
 public interface PolicyQuery {
 
+    /**
+     * @return The AccessQuery implementation.
+     */
     AccessQuery access();
+
+    /**
+     * @return The GraphQuery implementation.
+     */
     GraphQuery graph();
+
+    /**
+     * @return The ProhibitionsQuery implementation.
+     */
     ProhibitionsQuery prohibitions();
+
+    /**
+     * @return The ObligationsQuery implementation.
+     */
     ObligationsQuery obligations();
+
+    /**
+     * @return The OperationsQuery implementation.
+     */
     OperationsQuery operations();
+
+    /**
+     * @return The RoutinesQuery implementation.
+     */
     RoutinesQuery routines();
 }

src/main/java/gov/nist/csd/pm/pap/query/ProhibitionsQuery.java

@@ -6,6 +6,9 @@
 import java.util.Collection;
 import java.util.Map;
 
+/**
+ * Interface to query prohibitions.
+ */
 public interface ProhibitionsQuery {
 
     /**
@@ -33,7 +36,20 @@ public interface ProhibitionsQuery {
      */
     Prohibition getProhibition(String name) throws PMException;
 
+    /**
+     * Get the prohibitions the given subject inherits through assignments.
+     * @param subject The subject node.
+     * @return The prohibitions the given subject inherits.
+     * @throws PMException If any PM related exceptions occur in the implementing class.
+     */
     Collection<Prohibition> getInheritedProhibitionsFor(String subject) throws PMException;
+
+    /**
+     * Get the prohibitions that define the given container as a container condition.
+     * @param container The container to search for.
+     * @return The prohibitions that define the given container as a container condition.
+     * @throws PMException If any PM related exceptions occur in the implementing class.
+     */
     Collection<Prohibition> getProhibitionsWithContainer(String container) throws PMException;
 
 }

src/main/java/gov/nist/csd/pm/pap/query/RoutinesQuery.java

@@ -5,9 +5,24 @@
 
 import java.util.Collection;
 
+/**
+ * Interface to query routines.
+ */
 public interface RoutinesQuery {
 
+    /**
+     * Get the names of all admin routines.
+     * @return A collection of all the admin routine names.
+     * @throws PMException If there is an error in the PM.
+     */
     Collection<String> getAdminRoutineNames() throws PMException;
-    Routine getAdminRoutine(String routineName) throws PMException;
+
+    /**
+     * Get the admin operation with the given name.
+     * @param routineName The routine name.
+     * @return The Routine object.
+     * @throws PMException If there is an error in the PM.
+     */
+    Routine<?> getAdminRoutine(String routineName) throws PMException;
 
 }

src/main/java/gov/nist/csd/pm/pdp/query/AccessQueryAdjudicator.java

@@ -11,7 +11,6 @@
 
 import java.util.Collection;
 import java.util.Map;
-import java.util.Set;
 
 public class AccessQueryAdjudicator extends AccessQuerier {
 
@@ -86,7 +85,7 @@ public Explain explain(UserContext userCtx, String target) throws PMException {
     }
 
     @Override
-    public Set<String> computePersonalObjectSystem(UserContext userCtx) throws PMException {
+    public Collection<String> computePersonalObjectSystem(UserContext userCtx) throws PMException {
         PrivilegeChecker.check(pap, userCtx, userCtx.getUser(), AdminAccessRights.REVIEW_POLICY);
 
         return pap.query().access().computePersonalObjectSystem(userCtx);

src/test/java/gov/nist/csd/pm/pap/query/AccessQuerierTest.java

@@ -98,10 +98,10 @@ void testBuildPOS() throws PMException {
                 """;
         pap.deserialize(new UserContext("u1"), pml, new PMLDeserializer());
 
-        Set<String> u1 = pap.query().access().computePersonalObjectSystem(new UserContext("u1"));
+        Collection<String> u1 = pap.query().access().computePersonalObjectSystem(new UserContext("u1"));
         assertEquals(
                 Set.of("oa1", "oa2", "oa4"),
-                u1
+                new HashSet<>(u1)
         );
     }