Remove confusing permission override methods (discord-jda#2067)

Author: MinnDevelopment

Diff for: src/main/java/net/dv8tion/jda/api/entities/IPermissionContainer.java

@@ -18,7 +18,6 @@
 
 import net.dv8tion.jda.api.managers.channel.attribute.IPermissionContainerManager;
 import net.dv8tion.jda.api.requests.restaction.PermissionOverrideAction;
-import net.dv8tion.jda.internal.utils.Checks;
 
 import javax.annotation.CheckReturnValue;
 import javax.annotation.Nonnull;
@@ -109,65 +108,6 @@ default List<PermissionOverride> getRolePermissionOverrides()
                 .collect(Collectors.toList()));
     }
 
-    /**
-     * Creates a {@link net.dv8tion.jda.api.entities.PermissionOverride PermissionOverride}
-     * for the specified {@link net.dv8tion.jda.api.entities.Member Member} or {@link net.dv8tion.jda.api.entities.Role Role} in this GuildChannel.
-     * You can use {@link #putPermissionOverride(IPermissionHolder)} to replace existing overrides.
-     *
-     * <p>Possible ErrorResponses include:
-     * <ul>
-     *     <li>{@link net.dv8tion.jda.api.requests.ErrorResponse#UNKNOWN_CHANNEL UNKNOWN_CHANNEL}
-     *     <br>If this channel was already deleted</li>
-     *
-     *     <li>{@link net.dv8tion.jda.api.requests.ErrorResponse#MISSING_ACCESS MISSING_ACCESS}
-     *     <br>If we were removed from the Guild</li>
-     * </ul>
-     *
-     * @param  permissionHolder
-     *         The Member or Role to create an override for
-     *
-     * @throws net.dv8tion.jda.api.exceptions.InsufficientPermissionException
-     *         if we don't have the permission to {@link net.dv8tion.jda.api.Permission#MANAGE_PERMISSIONS MANAGE_PERMISSIONS}
-     * @throws IllegalArgumentException
-     *         if the specified permission holder is null or is not from {@link #getGuild()}
-     * @throws java.lang.IllegalStateException
-     *         If the specified permission holder already has a PermissionOverride. Use {@link #getPermissionOverride(IPermissionHolder)} to retrieve it.
-     *         You can use {@link #putPermissionOverride(IPermissionHolder)} to replace existing overrides.
-     *
-     * @return {@link PermissionOverrideAction PermissionOverrideAction}
-     *         Provides the newly created PermissionOverride for the specified permission holder
-     */
-    @Nonnull
-    @CheckReturnValue
-    default PermissionOverrideAction createPermissionOverride(@Nonnull IPermissionHolder permissionHolder)
-    {
-        Checks.notNull(permissionHolder, "PermissionHolder");
-        if (getPermissionOverride(permissionHolder) != null)
-            throw new IllegalStateException("Provided member already has a PermissionOverride in this channel!");
-
-        return putPermissionOverride(permissionHolder);
-    }
-
-    /**
-     * Creates a {@link net.dv8tion.jda.api.entities.PermissionOverride PermissionOverride}
-     * for the specified {@link net.dv8tion.jda.api.entities.Member Member} or {@link net.dv8tion.jda.api.entities.Role Role} in this GuildChannel.
-     * <br>If the permission holder already has an existing override it will be replaced.
-     *
-     * @param  permissionHolder
-     *         The Member or Role to create the override for
-     *
-     * @throws net.dv8tion.jda.api.exceptions.InsufficientPermissionException
-     *         if we don't have the permission to {@link net.dv8tion.jda.api.Permission#MANAGE_PERMISSIONS MANAGE_PERMISSIONS}
-     * @throws java.lang.IllegalArgumentException
-     *         If the provided permission holder is null or from a different guild
-     *
-     * @return {@link PermissionOverrideAction PermissionOverrideAction}
-     *         Provides the newly created PermissionOverride for the specified permission holder
-     */
-    @Nonnull
-    @CheckReturnValue
-    PermissionOverrideAction putPermissionOverride(@Nonnull IPermissionHolder permissionHolder);
-
     /**
      * Creates a new override or updates an existing one.
      * <br>This is similar to calling {@link PermissionOverride#getManager()} if an override exists.
@@ -183,15 +123,11 @@ default PermissionOverrideAction createPermissionOverride(@Nonnull IPermissionHo
      * @return {@link net.dv8tion.jda.api.requests.restaction.PermissionOverrideAction}
      *         <br>With the current settings of an existing override or a fresh override with no permissions set
      *
-     * @since  4.0.0
+     * @see    PermissionOverrideAction#clear(long)
+     * @see    PermissionOverrideAction#grant(long)
+     * @see    PermissionOverrideAction#deny(long)
      */
     @Nonnull
     @CheckReturnValue
-    default PermissionOverrideAction upsertPermissionOverride(@Nonnull IPermissionHolder permissionHolder)
-    {
-        PermissionOverride override = getPermissionOverride(permissionHolder);
-        if (override != null)
-            return override.getManager();
-        return putPermissionOverride(permissionHolder);
-    }
+    PermissionOverrideAction upsertPermissionOverride(@Nonnull IPermissionHolder permissionHolder);
 }

Diff for: src/main/java/net/dv8tion/jda/api/entities/PermissionOverride.java

@@ -30,8 +30,6 @@
  * permission overrides that can be set for channels.
  *
  * @see IPermissionContainer#upsertPermissionOverride(IPermissionHolder)
- * @see IPermissionContainer#createPermissionOverride(IPermissionHolder)
- * @see IPermissionContainer#putPermissionOverride(IPermissionHolder)
  *
  * @see IPermissionContainer#getPermissionOverrides()
  * @see IPermissionContainer#getPermissionOverride(IPermissionHolder)

Diff for: src/main/java/net/dv8tion/jda/api/requests/restaction/PermissionOverrideAction.java

@@ -38,8 +38,6 @@
  *
  * @see    net.dv8tion.jda.api.entities.PermissionOverride#getManager()
  * @see    IPermissionContainer#upsertPermissionOverride(IPermissionHolder)
- * @see    IPermissionContainer#createPermissionOverride(IPermissionHolder)
- * @see    IPermissionContainer#putPermissionOverride(IPermissionHolder)
  */
 public interface PermissionOverrideAction extends AuditableRestAction<PermissionOverride>
 {
@@ -131,7 +129,7 @@ default Guild getGuild()
      *
      * @return long value of granted permissions
      */
-    long getAllow();
+    long getAllowed();
 
     /**
      * Set of {@link net.dv8tion.jda.api.Permission Permissions}
@@ -143,7 +141,7 @@ default Guild getGuild()
     @Nonnull
     default EnumSet<Permission> getAllowedPermissions()
     {
-        return Permission.getPermissions(getAllow());
+        return Permission.getPermissions(getAllowed());
     }
 
     /**
@@ -156,7 +154,7 @@ default EnumSet<Permission> getAllowedPermissions()
      *
      * @return long value of denied permissions
      */
-    long getDeny();
+    long getDenied();
 
     /**
      * Set of {@link net.dv8tion.jda.api.Permission Permissions}
@@ -168,7 +166,7 @@ default EnumSet<Permission> getAllowedPermissions()
     @Nonnull
     default EnumSet<Permission> getDeniedPermissions()
     {
-        return Permission.getPermissions(getDeny());
+        return Permission.getPermissions(getDenied());
     }
 
     /**
@@ -240,12 +238,12 @@ default EnumSet<Permission> getInheritedPermissions()
      *
      * @return The current PermissionOverrideAction - for chaining convenience
      *
-     * @see    #setAllow(java.util.Collection) setAllow(Collection)
-     * @see    #setAllow(net.dv8tion.jda.api.Permission...) setAllow(Permission...)
+     * @see    #setAllowed(java.util.Collection) setAllow(Collection)
+     * @see    #setAllowed(net.dv8tion.jda.api.Permission...) setAllow(Permission...)
      */
     @Nonnull
     @CheckReturnValue
-    PermissionOverrideAction setAllow(long allowBits);
+    PermissionOverrideAction setAllowed(long allowBits);
 
     /**
      * Sets the value of explicitly granted permissions
@@ -268,16 +266,16 @@ default EnumSet<Permission> getInheritedPermissions()
      * @return The current PermissionOverrideAction - for chaining convenience
      *
      * @see    java.util.EnumSet EnumSet
-     * @see    #setAllow(net.dv8tion.jda.api.Permission...) setAllow(Permission...)
+     * @see    #setAllowed(net.dv8tion.jda.api.Permission...) setAllow(Permission...)
      */
     @Nonnull
     @CheckReturnValue
-    default PermissionOverrideAction setAllow(@Nullable Collection<Permission> permissions)
+    default PermissionOverrideAction setAllowed(@Nullable Collection<Permission> permissions)
     {
         if (permissions == null || permissions.isEmpty())
-            return setAllow(0);
+            return setAllowed(0);
         Checks.noneNull(permissions, "Permissions");
-        return setAllow(Permission.getRaw(permissions));
+        return setAllowed(Permission.getRaw(permissions));
     }
 
     /**
@@ -300,12 +298,12 @@ default PermissionOverrideAction setAllow(@Nullable Collection<Permission> permi
      */
     @Nonnull
     @CheckReturnValue
-    default PermissionOverrideAction setAllow(@Nullable Permission... permissions)
+    default PermissionOverrideAction setAllowed(@Nullable Permission... permissions)
     {
         if (permissions == null || permissions.length == 0)
-            return setAllow(0);
+            return setAllowed(0);
         Checks.noneNull(permissions, "Permissions");
-        return setAllow(Permission.getRaw(permissions));
+        return setAllowed(Permission.getRaw(permissions));
     }
 
     /**
@@ -389,12 +387,12 @@ default PermissionOverrideAction grant(@Nonnull Permission... permissions)
      *
      * @return The current PermissionOverrideAction - for chaining convenience
      *
-     * @see    #setDeny(java.util.Collection) setDeny(Collection)
-     * @see    #setDeny(net.dv8tion.jda.api.Permission...) setDeny(Permission...)
+     * @see    #setDenied(java.util.Collection) setDeny(Collection)
+     * @see    #setDenied(net.dv8tion.jda.api.Permission...) setDeny(Permission...)
      */
     @Nonnull
     @CheckReturnValue
-    PermissionOverrideAction setDeny(long denyBits);
+    PermissionOverrideAction setDenied(long denyBits);
 
     /**
      * Sets the value of explicitly denied permissions
@@ -417,16 +415,16 @@ default PermissionOverrideAction grant(@Nonnull Permission... permissions)
      * @return The current PermissionOverrideAction - for chaining convenience
      *
      * @see    java.util.EnumSet EnumSet
-     * @see    #setDeny(net.dv8tion.jda.api.Permission...) setDeny(Permission...)
+     * @see    #setDenied(net.dv8tion.jda.api.Permission...) setDeny(Permission...)
      */
     @Nonnull
     @CheckReturnValue
-    default PermissionOverrideAction setDeny(@Nullable Collection<Permission> permissions)
+    default PermissionOverrideAction setDenied(@Nullable Collection<Permission> permissions)
     {
         if (permissions == null || permissions.isEmpty())
-            return setDeny(0);
+            return setDenied(0);
         Checks.noneNull(permissions, "Permissions");
-        return setDeny(Permission.getRaw(permissions));
+        return setDenied(Permission.getRaw(permissions));
     }
 
     /**
@@ -449,12 +447,12 @@ default PermissionOverrideAction setDeny(@Nullable Collection<Permission> permis
      */
     @Nonnull
     @CheckReturnValue
-    default PermissionOverrideAction setDeny(@Nullable Permission... permissions)
+    default PermissionOverrideAction setDenied(@Nullable Permission... permissions)
     {
         if (permissions == null || permissions.length == 0)
-            return setDeny(0);
+            return setDenied(0);
         Checks.noneNull(permissions, "Permissions");
-        return setDeny(Permission.getRaw(permissions));
+        return setDenied(Permission.getRaw(permissions));
     }
 
     /**
@@ -584,7 +582,7 @@ default PermissionOverrideAction clear(@Nonnull Permission... permissions)
 
 
     /**
-     * Combination of {@link #setAllow(long)} and {@link #setDeny(long)}
+     * Combination of {@link #setAllowed(long)} and {@link #setDenied(long)}
      * <br>First sets the allow bits and then the deny bits.
      *
      * @param  allowBits
@@ -609,7 +607,7 @@ default PermissionOverrideAction clear(@Nonnull Permission... permissions)
     PermissionOverrideAction setPermissions(long allowBits, long denyBits);
 
     /**
-     * Combination of {@link #setAllow(java.util.Collection)} and {@link #setDeny(java.util.Collection)}
+     * Combination of {@link #setAllowed(java.util.Collection)} and {@link #setDenied(java.util.Collection)}
      * <br>First sets the granted permissions and then the denied permissions.
      * <br>If a passed collection is {@code null} it resets the represented value to {@code 0} - no permission specifics.
      *
@@ -637,6 +635,6 @@ default PermissionOverrideAction clear(@Nonnull Permission... permissions)
     @CheckReturnValue
     default PermissionOverrideAction setPermissions(@Nullable Collection<Permission> grantPermissions, @Nullable Collection<Permission> denyPermissions)
     {
-        return setAllow(grantPermissions).setDeny(denyPermissions);
+        return setAllowed(grantPermissions).setDenied(denyPermissions);
     }
 }

Diff for: src/main/java/net/dv8tion/jda/internal/entities/mixin/channel/attribute/IPermissionContainerMixin.java

@@ -53,11 +53,15 @@ default List<PermissionOverride> getPermissionOverrides()
 
     @Nonnull
     @Override
-    default PermissionOverrideAction putPermissionOverride(@Nonnull IPermissionHolder permissionHolder)
+    default PermissionOverrideAction upsertPermissionOverride(@Nonnull IPermissionHolder permissionHolder)
     {
         checkPermission(Permission.MANAGE_PERMISSIONS);
         Checks.notNull(permissionHolder, "PermissionHolder");
         Checks.check(permissionHolder.getGuild().equals(getGuild()), "Provided permission holder is not from the same guild as this channel!");
+
+        PermissionOverride override = getPermissionOverride(permissionHolder);
+        if (override != null)
+            return override.getManager();
         return new PermissionOverrideActionImpl(getJDA(), this, permissionHolder);
     }
 

Diff for: src/main/java/net/dv8tion/jda/internal/requests/restaction/PermissionOverrideActionImpl.java

@@ -152,21 +152,21 @@ public Member getMember()
     }
 
     @Override
-    public long getAllow()
+    public long getAllowed()
     {
         return getCurrentAllow();
     }
 
     @Override
-    public long getDeny()
+    public long getDenied()
     {
         return getCurrentDeny();
     }
 
     @Override
     public long getInherited()
     {
-        return ~getAllow() & ~getDeny();
+        return ~getAllowed() & ~getDenied();
     }
 
     @Override
@@ -184,7 +184,7 @@ public boolean isRole()
     @Nonnull
     @Override
     @CheckReturnValue
-    public PermissionOverrideActionImpl setAllow(long allowBits)
+    public PermissionOverrideActionImpl setAllowed(long allowBits)
     {
         checkPermissions(getOriginalAllow() ^ allowBits);
         this.allow = allowBits;
@@ -197,13 +197,13 @@ public PermissionOverrideActionImpl setAllow(long allowBits)
     @Override
     public PermissionOverrideAction grant(long allowBits)
     {
-        return setAllow(getCurrentAllow() | allowBits);
+        return setAllowed(getCurrentAllow() | allowBits);
     }
 
     @Nonnull
     @Override
     @CheckReturnValue
-    public PermissionOverrideActionImpl setDeny(long denyBits)
+    public PermissionOverrideActionImpl setDenied(long denyBits)
     {
         checkPermissions(getOriginalDeny() ^ denyBits);
         this.deny = denyBits;
@@ -216,14 +216,14 @@ public PermissionOverrideActionImpl setDeny(long denyBits)
     @Override
     public PermissionOverrideAction deny(long denyBits)
     {
-        return setDeny(getCurrentDeny() | denyBits);
+        return setDenied(getCurrentDeny() | denyBits);
     }
 
     @Nonnull
     @Override
     public PermissionOverrideAction clear(long inheritedBits)
     {
-        return setAllow(getCurrentAllow() & ~inheritedBits).setDeny(getCurrentDeny() & ~inheritedBits);
+        return setAllowed(getCurrentAllow() & ~inheritedBits).setDenied(getCurrentDeny() & ~inheritedBits);
     }
 
     protected void checkPermissions(long changed)
@@ -248,7 +248,7 @@ protected void checkPermissions(long changed)
     @CheckReturnValue
     public PermissionOverrideActionImpl setPermissions(long allowBits, long denyBits)
     {
-        return setAllow(allowBits).setDeny(denyBits);
+        return setAllowed(allowBits).setDenied(denyBits);
     }
 
     private long getCurrentAllow()