Merge remote-tracking branch 'origin'

infra/common/src/test/java/com/evolveum/midpoint/common/refinery/RelationRegistryDummyImpl.java

@@ -53,31 +53,6 @@ public boolean isOfKind(QName relation, RelationKindType kind) {
 		return kind == RelationKindType.MEMBERSHIP && (relation == null || QNameUtil.match(relation, ORG_DEFAULT));
 	}
 
-	@Override
-	public boolean isManager(QName relation) {
-		return false;
-	}
-
-	@Override
-	public boolean isDelegation(QName relation) {
-		return false;
-	}
-
-	@Override
-	public boolean isMembership(QName relation) {
-		return isOfKind(relation, RelationKindType.MEMBERSHIP);
-	}
-
-	@Override
-	public boolean isOwner(QName relation) {
-		return false;
-	}
-
-	@Override
-	public boolean isApprover(QName relation) {
-		return false;
-	}
-
 	@Override
 	public boolean processRelationOnLogin(QName relation) {
 		return false;
@@ -116,7 +91,7 @@ public QName normalizeRelation(QName relation) {
 	}
 
 	@Override
-	public void applyRelationConfiguration(SystemConfigurationType relationsDefinition) {
+	public void applyRelationConfiguration(SystemConfigurationType systemConfiguration) {
 	}
 
 	@Override

infra/schema/src/main/java/com/evolveum/midpoint/schema/RelationRegistry.java

@@ -20,64 +20,130 @@
 import com.evolveum.midpoint.xml.ns._public.common.common_3.RelationKindType;
 import com.evolveum.midpoint.xml.ns._public.common.common_3.SystemConfigurationType;
 import org.jetbrains.annotations.NotNull;
+import org.jetbrains.annotations.Nullable;
 
 import javax.xml.namespace.QName;
 import java.util.Collection;
 import java.util.List;
 
 /**
- * TODO think about precise place of this interface
+ * A component that holds current definition of object relations.
  *
  * @author mederly
  */
 public interface RelationRegistry {
 
+	/**
+	 * Returns all relation definitions: explicitly specified as well as built-in ones.
+	 * Invalid or duplicate definitions are filtered out and not mentioned here.
+	 *
+	 * Each relation is listed only once even if it can be referenced using various QNames (e.g. null, default, org:default).
+	 */
 	List<RelationDefinitionType> getRelationDefinitions();
 
-	RelationDefinitionType getRelationDefinition(QName relation);
-
-	// SchemaException is thrown as SystemException as it really should not occur
+	/**
+	 * Returns a relation definition for a specified relation name.
+	 * The relation name need not be normalized, i.e. all names for a relation might be used here
+	 * (e.g. null, default, org:default); resulting in the same definition.
+	 *
+	 * Returns null if the definition cannot be found.
+	 */
+	@Nullable RelationDefinitionType getRelationDefinition(QName relation);
 
+	/**
+	 * Returns true if the relation is of specified kind. The relation name need not be normalized.
+	 */
 	boolean isOfKind(QName relation, RelationKindType kind);
 
-	boolean isManager(QName relation);
+	default boolean isMembership(QName relation) {
+		return isOfKind(relation, RelationKindType.MEMBERSHIP);
+	}
 
-	boolean isDelegation(QName relation);
+	default boolean isManager(QName relation) {
+		return isOfKind(relation, RelationKindType.MANAGER);
+	}
 
-	boolean isMembership(QName relation);
+	default boolean isDelegation(QName relation) {
+		return isOfKind(relation, RelationKindType.DELEGATION);
+	}
 
-	boolean isOwner(QName relation);
+	@SuppressWarnings("unused")
+	default boolean isApprover(QName relation) {
+		return isOfKind(relation, RelationKindType.APPROVER);
+	}
 
-	boolean isApprover(QName relation);
+	@SuppressWarnings("unused")
+	default boolean isOwner(QName relation) {
+		return isOfKind(relation, RelationKindType.OWNER);
+	}
 
+	/**
+	 * Whether this kind of relations is processed on login. Currently only relations of MEMBERSHIP and DELEGATION kinds are.
+	 * This is to be configured in the future (MID-3581).
+	 */
 	boolean processRelationOnLogin(QName relation);
 
+	/**
+	 * Whether this kind of relations is processed on recompute. Currently only relations of MEMBERSHIP, MANAGER and DELEGATION kinds are.
+	 * This is to be configured in the future (MID-3581).
+	 */
 	boolean processRelationOnRecompute(QName relation);
 
+	/**
+	 * Whether this kind of relations is included in parentOrgRef. Currently only relations of MEMBERSHIP but *not* META kinds are.
+	 * This is to be configured in the future (MID-3581).
+	 */
 	boolean includeIntoParentOrgRef(QName relation);
 
+	/**
+	 * Returns the default relation i.e. the one that is equivalent to the null relation name.
+	 * Please do NOT use this information for queries nor determining the behavior of the relation! Use relation kinds instead.
+	 */
 	QName getDefaultRelation();
 
+	/**
+	 * Checks whether the relation is equivalent to the default one.
+	 * Please do NOT use this information for determining the behavior of the relation! Use relation kinds instead.
+	 */
+	boolean isDefault(QName relation);
+
+	/**
+	 * Returns all relations of a given kind. Note that the result might be an empty set; although it is a bad practice to
+	 * configure midPoint in that way. Unused relations are better hidden using categories.
+	 */
 	@NotNull
 	Collection<QName> getAllRelationsFor(RelationKindType kind);
 
-	QName getDefaultRelationFor(RelationKindType kind);
+	/**
+	 * Returns the default relation for a given kind. The result might be a null value; although it is a bad practice to
+	 * configure midPoint in that way. Unused relations are better hidden using categories.
+	 */
+	@Nullable QName getDefaultRelationFor(RelationKindType kind);
 
+	/**
+	 * Returns a normalized relation name, i.e. the one that is used in the "ref" item on the definition. It should be qualified
+	 * (so please DO NOT use unqualified relation names in the definitions!)
+	 *
+	 * If the relation is unknown, the relation name is returned unchanged.
+	 */
 	@NotNull
 	QName normalizeRelation(QName relation);
 
-	void applyRelationConfiguration(SystemConfigurationType relationsDefinition);
-
-	boolean isDefault(QName relation);
+	/**
+	 * This method should be called whenever midPoint determines that the relations definition in system configuration might
+	 * have been changed.
+	 */
+	void applyRelationConfiguration(SystemConfigurationType systemConfiguration);
 
 	/**
 	 * Returns aliases of a relation. Currently these are:
-	 *  - unnormalized version of the relation QNme
+	 *  - unqualified version of the relation QName
 	 *  - null if the relation is the default one
 	 *
+	 * --
 	 * In the future we might return some other values (e.g. explicitly configured aliases) as well.
 	 * But we would need to adapt prismContext.relationsEquivalent method and other comparison methods as well.
-	 * It is perhaps not worth the effort.
+	 * So it is perhaps not worth the effort.
 	 */
 	@NotNull
 	Collection<QName> getAliases(QName relation);

infra/schema/src/main/java/com/evolveum/midpoint/schema/relation/RelationRegistryImpl.java

@@ -124,31 +124,6 @@ public boolean isOfKind(QName relation, RelationKindType kind) {
 		return indexedRelationDefinitions.isOfKind(relation, kind);
 	}
 
-	@Override
-	public boolean isMembership(QName relation) {
-		return isOfKind(relation, RelationKindType.MEMBERSHIP);
-	}
-
-	@Override
-	public boolean isManager(QName relation) {
-		return isOfKind(relation, RelationKindType.MANAGER);
-	}
-
-	@Override
-	public boolean isDelegation(QName relation) {
-		return isOfKind(relation, RelationKindType.DELEGATION);
-	}
-
-	@Override
-	public boolean isOwner(QName relation) {
-		return isOfKind(relation, RelationKindType.OWNER);
-	}
-
-	@Override
-	public boolean isApprover(QName relation) {
-		return isOfKind(relation, RelationKindType.APPROVER);
-	}
-
 	@Override
 	public boolean processRelationOnLogin(QName relation) {
 		return indexedRelationDefinitions.processRelationOnLogin(relation);

infra/schema/src/main/resources/xml/ns/public/common/common-core-3.xsd

@@ -16319,7 +16319,6 @@
 				<xsd:annotation>
 					<xsd:documentation>
 						Membership relation, usually meaning "has" or "is member of".
-						Used as a relation value in object references.
 						Specifies that the subject is a member of organization, or that the subject
 						has been assigned a role in a way that he gets authorizations and other content
 						provided by that role.
@@ -16378,9 +16377,6 @@
 						a rule conflict during assignment (e.g. SoD conflict) or if there is any similar
 						situation.
 
-						This is a generic approver used for all the situation. The system may be customized
-						with more specific approver roles, e.g. technicalApprover, securityApprover, etc.
-
 						This approver is responsible for the use of the role, which mostly means
 						that he decides about role assignment. It is NOT meant to approve role changes.
 						Role owner is meant for that purpose.