Fix documentation add tutorial

Fixed some headings that made index's look strange.

Added xacml tutorial.

Issue-ID: POLICY-1842
Change-Id: Id6ab56e5d5d2a6b2fe37c8df5d3d70aa04776878
Signed-off-by: Pamela Dragosh <pdragosh@research.att.com>

10 files changed, 508 insertions, 0 deletions

diff --git a/docs/xacml/tutorial/app/pom.xml b/docs/xacml/tutorial/app/pom.xml
new file mode 100644
index 00000000..555f203f
--- /dev/null
+++ b/docs/xacml/tutorial/app/pom.xml
@@ -0,0 +1,28 @@
+<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+  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>org.onap.policy.tutorial</groupId>
+  <artifactId>tutorial</artifactId>
+  <version>0.0.1-SNAPSHOT</version>
+
+  <name>tutorial</name>
+
+  <properties>
+    <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
+  </properties>
+
+  <dependencies>
+    <dependency>
+      <groupId>junit</groupId>
+      <artifactId>junit</artifactId>
+      <version>4.12</version>
+      <scope>test</scope>
+    </dependency>
+    <dependency>
+      <groupId>org.onap.policy.xacml-pdp.applications</groupId>
+      <artifactId>common</artifactId>
+      <version>2.1.0-SNAPSHOT</version>
+    </dependency>
+  </dependencies>
+</project>
diff --git a/docs/xacml/tutorial/app/src/main/java/org/onap/policy/tutorial/tutorial/TutorialApplication.java b/docs/xacml/tutorial/app/src/main/java/org/onap/policy/tutorial/tutorial/TutorialApplication.java
new file mode 100644
index 00000000..99cbdcef
--- /dev/null
+++ b/docs/xacml/tutorial/app/src/main/java/org/onap/policy/tutorial/tutorial/TutorialApplication.java
@@ -0,0 +1,40 @@
+package org.onap.policy.tutorial.tutorial;
+
+import java.util.Arrays;
+import java.util.List;
+
+import org.onap.policy.models.tosca.authorative.concepts.ToscaPolicyTypeIdentifier;
+import org.onap.policy.pdp.xacml.application.common.ToscaPolicyTranslator;
+import org.onap.policy.pdp.xacml.application.common.std.StdXacmlApplicationServiceProvider;
+
+public class TutorialApplication extends StdXacmlApplicationServiceProvider {
+	
+	private final ToscaPolicyTypeIdentifier supportedPolicyType = new ToscaPolicyTypeIdentifier();
+	private final TutorialTranslator translator = new TutorialTranslator();
+
+    @Override
+    public String applicationName() {
+        return "tutorial";
+    }
+
+    @Override
+    public List<String> actionDecisionsSupported() {
+        return Arrays.asList("authorize");
+    }
+
+    @Override
+    public synchronized List<ToscaPolicyTypeIdentifier> supportedPolicyTypes() {
+        return Arrays.asList(supportedPolicyType);
+    }
+
+    @Override
+    public boolean canSupportPolicyType(ToscaPolicyTypeIdentifier policyTypeId) {
+    	return supportedPolicyType.equals(policyTypeId);
+    }
+
+    @Override
+	protected ToscaPolicyTranslator getTranslator(String type) {
+		return translator;
+	}
+
+}
diff --git a/docs/xacml/tutorial/app/src/main/java/org/onap/policy/tutorial/tutorial/TutorialRequest.java b/docs/xacml/tutorial/app/src/main/java/org/onap/policy/tutorial/tutorial/TutorialRequest.java
new file mode 100644
index 00000000..33442b27
--- /dev/null
+++ b/docs/xacml/tutorial/app/src/main/java/org/onap/policy/tutorial/tutorial/TutorialRequest.java
@@ -0,0 +1,76 @@
+package org.onap.policy.tutorial.tutorial;
+
+import java.util.Map;
+import java.util.Map.Entry;
+
+import org.onap.policy.models.decisions.concepts.DecisionRequest;
+
+import com.att.research.xacml.std.annotations.XACMLAction;
+import com.att.research.xacml.std.annotations.XACMLRequest;
+import com.att.research.xacml.std.annotations.XACMLResource;
+import com.att.research.xacml.std.annotations.XACMLSubject;
+
+import lombok.Getter;
+import lombok.Setter;
+import lombok.ToString;
+
+@Getter
+@Setter
+@ToString
+@XACMLRequest(ReturnPolicyIdList = true)
+public class TutorialRequest {
+    @XACMLSubject(includeInResults = true)
+    private String onapName;
+
+    @XACMLSubject(attributeId = "urn:org:onap:onap-component", includeInResults = true)
+    private String onapComponent;
+
+    @XACMLSubject(attributeId = "urn:org:onap:onap-instance",  includeInResults = true)
+    private String onapInstance;
+
+    @XACMLAction()
+    private String action;
+
+    @XACMLResource(attributeId = "urn:org:onap:tutorial-user", includeInResults = true)
+    private String user;
+
+    @XACMLResource(attributeId = "urn:org:onap:tutorial-entity", includeInResults = true)
+    private String entity;
+
+    @XACMLResource(attributeId = "urn:org:onap:tutorial-permission", includeInResults = true)
+    private String permission;
+
+    public static TutorialRequest createRequest(DecisionRequest decisionRequest) {
+    	//
+    	// Create our object
+    	//
+    	TutorialRequest request = new TutorialRequest();
+        //
+        // Add the subject attributes
+        //
+        request.onapName = decisionRequest.getOnapName();
+        request.onapComponent = decisionRequest.getOnapComponent();
+        request.onapInstance = decisionRequest.getOnapInstance();
+        //
+        // Add the action attribute
+        //
+        request.action = decisionRequest.getAction();
+        //
+        // Add the resource attributes
+        //
+        Map<String, Object> resources = decisionRequest.getResource();
+        for (Entry<String, Object> entrySet : resources.entrySet()) {
+            if ("user".equals(entrySet.getKey())) {
+            	request.user = entrySet.getValue().toString();
+            }
+            if ("entity".equals(entrySet.getKey())) {
+            	request.entity = entrySet.getValue().toString();
+            }
+            if ("permission".equals(entrySet.getKey())) {
+            	request.permission = entrySet.getValue().toString();
+            }
+        }    	
+    	
+    	return request;
+    }
+}
diff --git a/docs/xacml/tutorial/app/src/main/java/org/onap/policy/tutorial/tutorial/TutorialTranslator.java b/docs/xacml/tutorial/app/src/main/java/org/onap/policy/tutorial/tutorial/TutorialTranslator.java
new file mode 100644
index 00000000..d118aabf
--- /dev/null
+++ b/docs/xacml/tutorial/app/src/main/java/org/onap/policy/tutorial/tutorial/TutorialTranslator.java
@@ -0,0 +1,161 @@
+package org.onap.policy.tutorial.tutorial;
+
+import java.util.List;
+import java.util.Map;
+
+import org.onap.policy.models.decisions.concepts.DecisionRequest;
+import org.onap.policy.models.decisions.concepts.DecisionResponse;
+import org.onap.policy.models.tosca.authorative.concepts.ToscaPolicy;
+import org.onap.policy.pdp.xacml.application.common.ToscaDictionary;
+import org.onap.policy.pdp.xacml.application.common.ToscaPolicyConversionException;
+import org.onap.policy.pdp.xacml.application.common.ToscaPolicyTranslator;
+import org.onap.policy.pdp.xacml.application.common.ToscaPolicyTranslatorUtils;
+
+import com.att.research.xacml.api.DataTypeException;
+import com.att.research.xacml.api.Decision;
+import com.att.research.xacml.api.Identifier;
+import com.att.research.xacml.api.Request;
+import com.att.research.xacml.api.Response;
+import com.att.research.xacml.api.Result;
+import com.att.research.xacml.api.XACML3;
+import com.att.research.xacml.std.IdentifierImpl;
+import com.att.research.xacml.std.annotations.RequestParser;
+
+import oasis.names.tc.xacml._3_0.core.schema.wd_17.AnyOfType;
+import oasis.names.tc.xacml._3_0.core.schema.wd_17.EffectType;
+import oasis.names.tc.xacml._3_0.core.schema.wd_17.MatchType;
+import oasis.names.tc.xacml._3_0.core.schema.wd_17.PolicyType;
+import oasis.names.tc.xacml._3_0.core.schema.wd_17.RuleType;
+import oasis.names.tc.xacml._3_0.core.schema.wd_17.TargetType;
+
+public class TutorialTranslator implements ToscaPolicyTranslator {
+	
+	private static final Identifier ID_TUTORIAL_USER =
+            new IdentifierImpl(ToscaDictionary.ID_URN_ONAP, "tutorial-user");
+	private static final Identifier ID_TUTORIAL_ENTITY =
+            new IdentifierImpl(ToscaDictionary.ID_URN_ONAP, "tutorial-entity");
+	private static final Identifier ID_TUTORIAL_PERM =
+            new IdentifierImpl(ToscaDictionary.ID_URN_ONAP, "tutorial-perm");
+
+	public PolicyType convertPolicy(ToscaPolicy toscaPolicy) throws ToscaPolicyConversionException {
+		//
+		// Here is our policy with a version and default combining algo
+		//
+        PolicyType newPolicyType = new PolicyType();
+        newPolicyType.setPolicyId(toscaPolicy.getMetadata().get("policy-id"));
+        newPolicyType.setVersion(toscaPolicy.getMetadata().get("policy-version"));
+        //
+        // When choosing the rule combining algorithm, be sure to be mindful of the
+        // setting xacml.att.policyFinderFactory.combineRootPolicies in the
+        // xacml.properties file. As that choice for ALL the policies together may have
+        // an impact on the decision rendered from each individual policy.
+        //
+        // In this case, we will only produce XACML rules for permissions. If no permission
+        // combo exists, then the default is to deny.
+        //
+        newPolicyType.setRuleCombiningAlgId(XACML3.ID_RULE_DENY_UNLESS_PERMIT.stringValue());
+        //
+        // Create the target for the Policy.
+        //
+        // For simplicity, let's just match on the action "authorize" and the user
+        //
+        MatchType matchAction = ToscaPolicyTranslatorUtils.buildMatchTypeDesignator(
+                XACML3.ID_FUNCTION_STRING_EQUAL,
+                "authorize",
+                XACML3.ID_DATATYPE_STRING,
+                XACML3.ID_ACTION,
+                XACML3.ID_ATTRIBUTE_CATEGORY_ACTION);
+        Map<String, Object> props = toscaPolicy.getProperties();
+        String user = props.get("user").toString();
+        MatchType matchUser = ToscaPolicyTranslatorUtils.buildMatchTypeDesignator(
+                XACML3.ID_FUNCTION_STRING_EQUAL,
+                user,
+                XACML3.ID_DATATYPE_STRING,
+                ID_TUTORIAL_USER,
+                XACML3.ID_ATTRIBUTE_CATEGORY_RESOURCE);
+        AnyOfType anyOf = new AnyOfType();
+        //
+        // Create AllOf (AND) of just Policy Id
+        //
+        anyOf.getAllOf().add(ToscaPolicyTranslatorUtils.buildAllOf(matchAction));
+        anyOf.getAllOf().add(ToscaPolicyTranslatorUtils.buildAllOf(matchUser));
+        TargetType target = new TargetType();
+        target.getAnyOf().add(anyOf);
+        newPolicyType.setTarget(target);
+        //
+        // Now add the rule for each permission
+        //
+        List<Object> permissions = (List<Object>) props.get("permissions");
+		for (Object permission : permissions) {
+			
+            MatchType matchEntity = ToscaPolicyTranslatorUtils.buildMatchTypeDesignator(
+                    XACML3.ID_FUNCTION_STRING_EQUAL,
+                    ((Map<String, String>) permission).get("entity"),
+                    XACML3.ID_DATATYPE_STRING,
+                    ID_TUTORIAL_ENTITY,
+                    XACML3.ID_ATTRIBUTE_CATEGORY_RESOURCE);
+        	
+            MatchType matchPermission = ToscaPolicyTranslatorUtils.buildMatchTypeDesignator(
+                    XACML3.ID_FUNCTION_STRING_EQUAL,
+                    ((Map<String, String>) permission).get("permission"),
+                    XACML3.ID_DATATYPE_STRING,
+                    ID_TUTORIAL_PERM,
+                    XACML3.ID_ATTRIBUTE_CATEGORY_RESOURCE);
+            anyOf = new AnyOfType();
+            anyOf.getAllOf().add(ToscaPolicyTranslatorUtils.buildAllOf(matchEntity));
+            anyOf.getAllOf().add(ToscaPolicyTranslatorUtils.buildAllOf(matchPermission));
+            target = new TargetType();
+            target.getAnyOf().add(anyOf);
+            
+            RuleType rule = new RuleType();
+            rule.setDescription("Default is to PERMIT if the policy matches.");
+            rule.setRuleId(newPolicyType.getPolicyId() + ":rule");
+            rule.setEffect(EffectType.PERMIT);
+            rule.setTarget(target);
+            
+            newPolicyType.getCombinerParametersOrRuleCombinerParametersOrVariableDefinition().add(rule);
+        }
+		return newPolicyType;
+	}
+
+	public Request convertRequest(DecisionRequest request) {
+        try {
+            return RequestParser.parseRequest(TutorialRequest.createRequest(request));
+        } catch (IllegalArgumentException | IllegalAccessException | DataTypeException e) {
+        }
+		return null;
+	}
+
+	public DecisionResponse convertResponse(Response xacmlResponse) {
+        DecisionResponse decisionResponse = new DecisionResponse();
+        //
+        // Iterate through all the results
+        //
+        for (Result xacmlResult : xacmlResponse.getResults()) {
+            //
+            // Check the result
+            //
+            if (xacmlResult.getDecision() == Decision.PERMIT) {
+                //
+                // Just simply return a Permit response
+                //
+                decisionResponse.setStatus(Decision.PERMIT.toString());
+            }
+            if (xacmlResult.getDecision() == Decision.DENY) {
+                //
+                // Just simply return a Deny response
+                //
+                decisionResponse.setStatus(Decision.DENY.toString());
+            }
+            if (xacmlResult.getDecision() == Decision.NOTAPPLICABLE) {
+                //
+                // There is no guard policy, so we return a permit
+                //
+                decisionResponse.setStatus(Decision.PERMIT.toString());
+            }
+        }
+
+        return decisionResponse;
+	}
+
+}
diff --git a/docs/xacml/tutorial/app/src/main/resources/META-INF/services/org.onap.policy.pdp.xacml.application.common.XacmlApplicationServiceProvider b/docs/xacml/tutorial/app/src/main/resources/META-INF/services/org.onap.policy.pdp.xacml.application.common.XacmlApplicationServiceProvider
new file mode 100644
index 00000000..942cc596
--- /dev/null
+++ b/docs/xacml/tutorial/app/src/main/resources/META-INF/services/org.onap.policy.pdp.xacml.application.common.XacmlApplicationServiceProvider
@@ -0,0 +1 @@
+org.onap.policy.tutorial.tutorial.TutorialApplication
\ No newline at end of file
diff --git a/docs/xacml/tutorial/app/src/test/java/org/onap/policy/tutorial/tutorial/TutorialApplicationTest.java b/docs/xacml/tutorial/app/src/test/java/org/onap/policy/tutorial/tutorial/TutorialApplicationTest.java
new file mode 100644
index 00000000..7a1c2f94
--- /dev/null
+++ b/docs/xacml/tutorial/app/src/test/java/org/onap/policy/tutorial/tutorial/TutorialApplicationTest.java
@@ -0,0 +1,93 @@
+package org.onap.policy.tutorial.tutorial;
+
+import java.io.File;
+import java.io.IOException;
+import java.util.Iterator;
+import java.util.List;
+import java.util.Properties;
+import java.util.ServiceLoader;
+
+import org.apache.commons.lang3.tuple.Pair;
+import org.junit.BeforeClass;
+import org.junit.ClassRule;
+import org.junit.Test;
+import org.junit.rules.TemporaryFolder;
+import org.onap.policy.common.utils.coder.CoderException;
+import org.onap.policy.common.utils.coder.StandardCoder;
+import org.onap.policy.common.utils.resources.TextFileUtils;
+import org.onap.policy.models.decisions.concepts.DecisionRequest;
+import org.onap.policy.models.decisions.concepts.DecisionResponse;
+import org.onap.policy.models.tosca.authorative.concepts.ToscaPolicy;
+import org.onap.policy.pdp.xacml.application.common.TestUtils;
+import org.onap.policy.pdp.xacml.application.common.XacmlApplicationException;
+import org.onap.policy.pdp.xacml.application.common.XacmlApplicationServiceProvider;
+import org.onap.policy.pdp.xacml.application.common.XacmlPolicyUtils;
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+
+import com.att.research.xacml.api.Response;
+
+public class TutorialApplicationTest {
+	private static final Logger LOGGER = LoggerFactory.getLogger(TutorialApplicationTest.class);
+    private static Properties properties = new Properties();
+    private static File propertiesFile;
+    private static XacmlApplicationServiceProvider service;
+    private static StandardCoder gson = new StandardCoder();
+
+    @ClassRule
+    public static final TemporaryFolder policyFolder = new TemporaryFolder();
+
+    @BeforeClass
+    public static void setup() throws Exception {
+        //
+        // Setup our temporary folder
+        //
+        XacmlPolicyUtils.FileCreator myCreator = (String filename) -> policyFolder.newFile(filename);
+        propertiesFile = XacmlPolicyUtils.copyXacmlPropertiesContents("src/test/resources/xacml.properties",
+                properties, myCreator);
+        //
+        // Load XacmlApplicationServiceProvider service
+        //
+        ServiceLoader<XacmlApplicationServiceProvider> applicationLoader =
+                ServiceLoader.load(XacmlApplicationServiceProvider.class);
+        //
+        // Look for our class instance and save it
+        //
+        Iterator<XacmlApplicationServiceProvider> iterator = applicationLoader.iterator();
+        while (iterator.hasNext()) {
+            XacmlApplicationServiceProvider application = iterator.next();
+            //
+            // Is it our service?
+            //
+            if (application instanceof TutorialApplication) {
+            	service = application;
+            }
+        }
+        //
+        // Tell the application to initialize based on the properties file
+        // we just built for it.
+        //
+        service.initialize(propertiesFile.toPath().getParent());
+	}
+    
+    @Test
+    public void test() throws CoderException, XacmlApplicationException, IOException {
+        //
+        // Now load the tutorial policies.
+        //
+        TestUtils.loadPolicies("src/test/resources/tutorial-policies.yaml", service);
+        //
+        // Load a Decision request
+        //
+        DecisionRequest decisionRequest = gson.decode(
+                TextFileUtils
+                .getTextFileAsString("src/test/resources/tutorial-decision-request.json"),
+                DecisionRequest.class);
+    	//
+        // Test a decision
+        //
+        Pair<DecisionResponse, Response> decision = service.makeDecision(decisionRequest);
+        LOGGER.info(decision.getLeft().toString());
+    }
+
+}
diff --git a/docs/xacml/tutorial/app/src/test/resources/tutorial-decision-request.json b/docs/xacml/tutorial/app/src/test/resources/tutorial-decision-request.json
new file mode 100644
index 00000000..8c1ec10c
--- /dev/null
+++ b/docs/xacml/tutorial/app/src/test/resources/tutorial-decision-request.json
@@ -0,0 +1,12 @@
+{
+  "ONAPName": "TutorialPEP",
+  "ONAPComponent": "TutorialPEPComponent",
+  "ONAPInstance": "TutorialPEPInstance",
+  "requestId": "unique-request-id-tutorial",
+  "action": "authorize",
+  "resource": {
+    "user": "demo",
+    "entity": "foo",
+    "permission" : "read"
+  }
+}
diff --git a/docs/xacml/tutorial/app/src/test/resources/tutorial-policies.yaml b/docs/xacml/tutorial/app/src/test/resources/tutorial-policies.yaml
new file mode 100644
index 00000000..90a1f9ed
--- /dev/null
+++ b/docs/xacml/tutorial/app/src/test/resources/tutorial-policies.yaml
@@ -0,0 +1,32 @@
+tosca_definitions_version: tosca_simple_yaml_1_0_0
+topology_template:
+    policies:
+        -
+            onap.policy.tutorial.demo:
+                type: onap.policies.Authorization
+                version: 1.0.0
+                metadata:
+                    policy-id: onap.policy.tutorial.demo
+                    policy-version: 1
+                properties:
+                    user: demo
+                    permissions:
+                        -
+                            entity: foo
+                            permission: read
+                        -
+                            entity: foo
+                            permission: write
+        -
+            onap.policy.tutorial.audit:
+                type: onap.policies.Authorization
+                version: 1.0.0
+                metadata:
+                    policy-id: onap.policy.tutorial.bar
+                    policy-version: 1
+                properties:
+                    user: audit
+                    permissions:
+                        -
+                            entity: foo
+                            permission: read
diff --git a/docs/xacml/tutorial/app/src/test/resources/tutorial-policy-type.yaml b/docs/xacml/tutorial/app/src/test/resources/tutorial-policy-type.yaml
new file mode 100644
index 00000000..181a73c5
--- /dev/null
+++ b/docs/xacml/tutorial/app/src/test/resources/tutorial-policy-type.yaml
@@ -0,0 +1,34 @@
+tosca_definitions_version: tosca_simple_yaml_1_0_0
+policy_types:
+  -
+    onap.policies.Authorization:
+        derived_from: tosca.policies.Root
+        version: 1.0.0
+        description: Example tutorial policy type for doing user authorization
+        properties:
+            user:
+                type: string
+                required: true
+                description: The unique user name
+            permissions:
+                type: list
+                required: true
+                description: A list of resource permissions
+                entry_schema:
+                    type: onap.datatypes.Tutorial
+data_types:
+  -
+    onap.datatypes.Tutorial:
+    derived_from: tosca.datatypes.Root
+    version: 1.0.0
+    properties:
+        entity:
+            type: string
+            required: true
+            description: The resource
+        permission:
+            type: string
+            required: true
+            description: The permission level
+            constraints:
+                - valid_values: [read, write, delete]
diff --git a/docs/xacml/tutorial/app/src/test/resources/xacml.properties b/docs/xacml/tutorial/app/src/test/resources/xacml.properties
new file mode 100644
index 00000000..277b098e
--- /dev/null
+++ b/docs/xacml/tutorial/app/src/test/resources/xacml.properties
@@ -0,0 +1,31 @@
+#
+# Properties that the embedded PDP engine uses to configure and load
+#
+# Standard API Factories
+#
+xacml.dataTypeFactory=com.att.research.xacml.std.StdDataTypeFactory
+xacml.pdpEngineFactory=com.att.research.xacmlatt.pdp.ATTPDPEngineFactory
+xacml.pepEngineFactory=com.att.research.xacml.std.pep.StdEngineFactory
+xacml.pipFinderFactory=com.att.research.xacml.std.pip.StdPIPFinderFactory
+xacml.traceEngineFactory=com.att.research.xacml.std.trace.LoggingTraceEngineFactory
+#
+# AT&T PDP Implementation Factories
+#
+xacml.att.evaluationContextFactory=com.att.research.xacmlatt.pdp.std.StdEvaluationContextFactory
+xacml.att.combiningAlgorithmFactory=com.att.research.xacmlatt.pdp.std.StdCombiningAlgorithmFactory
+xacml.att.functionDefinitionFactory=com.att.research.xacmlatt.pdp.std.StdFunctionDefinitionFactory
+#
+# ONAP PDP Implementation Factories
+#
+xacml.att.policyFinderFactory=org.onap.policy.pdp.xacml.application.common.OnapPolicyFinderFactory
+
+#
+# Use a root combining algorithm
+#
+xacml.att.policyFinderFactory.combineRootPolicies=urn:oasis:names:tc:xacml:3.0:policy-combining-algorithm:deny-overrides
+
+#
+# Policies to load
+#
+xacml.rootPolicies=
+xacml.referencedPolicies=
\ No newline at end of file