Skip to content

Commit 43035db

Browse files
ShengaeroMinnDevelopment
Shengaero
authored and
MinnDevelopment
committed
Added a CategoryOrderAction, documentation, and access points (discord-jda#578)
1 parent 48f59c9 commit 43035db

File tree

6 files changed

+304
-24
lines changed

6 files changed

+304
-24
lines changed

‎src/main/java/net/dv8tion/jda/core/entities/Category.java

Lines changed: 53 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -17,6 +17,7 @@
1717
package net.dv8tion.jda.core.entities;
1818

1919
import net.dv8tion.jda.core.requests.restaction.ChannelAction;
20+
import net.dv8tion.jda.core.requests.restaction.order.CategoryOrderAction;
2021

2122
import javax.annotation.CheckReturnValue;
2223
import java.util.List;
@@ -120,4 +121,56 @@ public interface Category extends Channel, Comparable<Category>
120121
*/
121122
@CheckReturnValue
122123
ChannelAction createVoiceChannel(String name);
124+
125+
/**
126+
* Modifies the positional order of this Category's nested {@link #getTextChannels() TextChannels}.
127+
* <br>This uses an extension of {@link net.dv8tion.jda.core.requests.restaction.order.ChannelOrderAction ChannelOrderAction}
128+
* specialized for ordering the nested {@link net.dv8tion.jda.core.entities.TextChannel TextChannels} of this
129+
* {@link net.dv8tion.jda.core.entities.Category Category}.
130+
* <br>Like {@code ChannelOrderAction}, the returned {@link net.dv8tion.jda.core.requests.restaction.order.CategoryOrderAction CategoryOrderAction}
131+
* can be used to move TextChannels {@link net.dv8tion.jda.core.requests.restaction.order.OrderAction#moveUp(int) up},
132+
* {@link net.dv8tion.jda.core.requests.restaction.order.OrderAction#moveDown(int) down}, or
133+
* {@link net.dv8tion.jda.core.requests.restaction.order.OrderAction#moveTo(int) to} a specific position.
134+
* <br>This uses <b>ascending</b> order with a 0 based index.
135+
*
136+
* <p>Possible {@link net.dv8tion.jda.core.requests.ErrorResponse ErrorResponses} include:
137+
* <ul>
138+
* <li>{@link net.dv8tion.jda.core.requests.ErrorResponse#UNKNOWN_CHANNEL UNNKOWN_CHANNEL}
139+
* <br>One of the channels has been deleted before the completion of the task.</li>
140+
*
141+
* <li>{@link net.dv8tion.jda.core.requests.ErrorResponse#MISSING_ACCESS MISSING_ACCESS}
142+
* <br>The currently logged in account was removed from the Guild.</li>
143+
* </ul>
144+
*
145+
* @return A {@link net.dv8tion.jda.core.requests.restaction.order.CategoryOrderAction CategoryOrderAction} for
146+
* ordering the Category's {@link net.dv8tion.jda.core.entities.TextChannel TextChannels}.
147+
*/
148+
@CheckReturnValue
149+
CategoryOrderAction<TextChannel> modifyTextChannelPositions();
150+
151+
/**
152+
* Modifies the positional order of this Category's nested {@link #getVoiceChannels() VoiceChannels}.
153+
* <br>This uses an extension of {@link net.dv8tion.jda.core.requests.restaction.order.ChannelOrderAction ChannelOrderAction}
154+
* specialized for ordering the nested {@link net.dv8tion.jda.core.entities.VoiceChannel VoiceChannels} of this
155+
* {@link net.dv8tion.jda.core.entities.Category Category}.
156+
* <br>Like {@code ChannelOrderAction}, the returned {@link net.dv8tion.jda.core.requests.restaction.order.CategoryOrderAction CategoryOrderAction}
157+
* can be used to move VoiceChannels {@link net.dv8tion.jda.core.requests.restaction.order.OrderAction#moveUp(int) up},
158+
* {@link net.dv8tion.jda.core.requests.restaction.order.OrderAction#moveDown(int) down}, or
159+
* {@link net.dv8tion.jda.core.requests.restaction.order.OrderAction#moveTo(int) to} a specific position.
160+
* <br>This uses <b>ascending</b> order with a 0 based index.
161+
*
162+
* <p>Possible {@link net.dv8tion.jda.core.requests.ErrorResponse ErrorResponses} include:
163+
* <ul>
164+
* <li>{@link net.dv8tion.jda.core.requests.ErrorResponse#UNKNOWN_CHANNEL UNNKOWN_CHANNEL}
165+
* <br>One of the channels has been deleted before the completion of the task.</li>
166+
*
167+
* <li>{@link net.dv8tion.jda.core.requests.ErrorResponse#MISSING_ACCESS MISSING_ACCESS}
168+
* <br>The currently logged in account was removed from the Guild.</li>
169+
* </ul>
170+
*
171+
* @return A {@link net.dv8tion.jda.core.requests.restaction.order.CategoryOrderAction CategoryOrderAction} for
172+
* ordering the Category's {@link net.dv8tion.jda.core.entities.VoiceChannel VoiceChannels}.
173+
*/
174+
@CheckReturnValue
175+
CategoryOrderAction<VoiceChannel> modifyVoiceChannelPositions();
123176
}

‎src/main/java/net/dv8tion/jda/core/entities/impl/CategoryImpl.java

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -21,6 +21,7 @@
2121
import net.dv8tion.jda.core.requests.RestAction;
2222
import net.dv8tion.jda.core.requests.restaction.ChannelAction;
2323
import net.dv8tion.jda.core.requests.restaction.InviteAction;
24+
import net.dv8tion.jda.core.requests.restaction.order.CategoryOrderAction;
2425
import net.dv8tion.jda.core.utils.Checks;
2526
import net.dv8tion.jda.core.utils.MiscUtil;
2627

@@ -159,6 +160,18 @@ public ChannelAction createVoiceChannel(String name)
159160
return action;
160161
}
161162

163+
@Override
164+
public CategoryOrderAction<TextChannel> modifyTextChannelPositions()
165+
{
166+
return getGuild().getController().modifyTextChannelPositions(this);
167+
}
168+
169+
@Override
170+
public CategoryOrderAction<VoiceChannel> modifyVoiceChannelPositions()
171+
{
172+
return getGuild().getController().modifyVoiceChannelPositions(this);
173+
}
174+
162175
@Override
163176
public String toString()
164177
{

‎src/main/java/net/dv8tion/jda/core/managers/GuildController.java

Lines changed: 69 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -34,6 +34,7 @@
3434
import net.dv8tion.jda.core.requests.restaction.ChannelAction;
3535
import net.dv8tion.jda.core.requests.restaction.RoleAction;
3636
import net.dv8tion.jda.core.requests.restaction.WebhookAction;
37+
import net.dv8tion.jda.core.requests.restaction.order.CategoryOrderAction;
3738
import net.dv8tion.jda.core.requests.restaction.order.ChannelOrderAction;
3839
import net.dv8tion.jda.core.requests.restaction.order.RoleOrderAction;
3940
import net.dv8tion.jda.core.utils.Checks;
@@ -2229,6 +2230,74 @@ public ChannelOrderAction<VoiceChannel> modifyVoiceChannelPositions()
22292230
return new ChannelOrderAction<>(guild, ChannelType.VOICE);
22302231
}
22312232

2233+
/**
2234+
* Modifies the positional order of {@link net.dv8tion.jda.core.entities.Category#getTextChannels() Category#getTextChannels()}
2235+
* using an extension of {@link net.dv8tion.jda.core.requests.restaction.order.ChannelOrderAction ChannelOrderAction}
2236+
* specialized for ordering the nested {@link net.dv8tion.jda.core.entities.TextChannel TextChannels} of this
2237+
* {@link net.dv8tion.jda.core.entities.Category Category}.
2238+
* <br>Like {@code ChannelOrderAction}, the returned {@link net.dv8tion.jda.core.requests.restaction.order.CategoryOrderAction CategoryOrderAction}
2239+
* can be used to move TextChannels {@link net.dv8tion.jda.core.requests.restaction.order.OrderAction#moveUp(int) up},
2240+
* {@link net.dv8tion.jda.core.requests.restaction.order.OrderAction#moveDown(int) down}, or
2241+
* {@link net.dv8tion.jda.core.requests.restaction.order.OrderAction#moveTo(int) to} a specific position.
2242+
* <br>This uses <b>ascending</b> order with a 0 based index.
2243+
*
2244+
* <p>Possible {@link net.dv8tion.jda.core.requests.ErrorResponse ErrorResponses} include:
2245+
* <ul>
2246+
* <li>{@link net.dv8tion.jda.core.requests.ErrorResponse#UNKNOWN_CHANNEL UNNKOWN_CHANNEL}
2247+
* <br>One of the channels has been deleted before the completion of the task.</li>
2248+
*
2249+
* <li>{@link net.dv8tion.jda.core.requests.ErrorResponse#MISSING_ACCESS MISSING_ACCESS}
2250+
* <br>The currently logged in account was removed from the Guild.</li>
2251+
* </ul>
2252+
*
2253+
* @param category
2254+
* The {@link net.dv8tion.jda.core.entities.Category Category} to order
2255+
* {@link net.dv8tion.jda.core.entities.TextChannel TextChannels} from.
2256+
*
2257+
* @return {@link net.dv8tion.jda.core.requests.restaction.order.CategoryOrderAction CategoryOrderAction} - Type: {@link net.dv8tion.jda.core.entities.TextChannel TextChannel}
2258+
*/
2259+
@CheckReturnValue
2260+
public CategoryOrderAction<TextChannel> modifyTextChannelPositions(Category category)
2261+
{
2262+
Checks.notNull(category, "Category");
2263+
checkGuild(category.getGuild(), "Category");
2264+
return new CategoryOrderAction<>(category, ChannelType.TEXT);
2265+
}
2266+
2267+
/**
2268+
* Modifies the positional order of {@link net.dv8tion.jda.core.entities.Category#getVoiceChannels() Category#getVoiceChannels()}
2269+
* using an extension of {@link net.dv8tion.jda.core.requests.restaction.order.ChannelOrderAction ChannelOrderAction}
2270+
* specialized for ordering the nested {@link net.dv8tion.jda.core.entities.VoiceChannel VoiceChannels} of this
2271+
* {@link net.dv8tion.jda.core.entities.Category Category}.
2272+
* <br>Like {@code ChannelOrderAction}, the returned {@link net.dv8tion.jda.core.requests.restaction.order.CategoryOrderAction CategoryOrderAction}
2273+
* can be used to move VoiceChannels {@link net.dv8tion.jda.core.requests.restaction.order.OrderAction#moveUp(int) up},
2274+
* {@link net.dv8tion.jda.core.requests.restaction.order.OrderAction#moveDown(int) down}, or
2275+
* {@link net.dv8tion.jda.core.requests.restaction.order.OrderAction#moveTo(int) to} a specific position.
2276+
* <br>This uses <b>ascending</b> order with a 0 based index.
2277+
*
2278+
* <p>Possible {@link net.dv8tion.jda.core.requests.ErrorResponse ErrorResponses} include:
2279+
* <ul>
2280+
* <li>{@link net.dv8tion.jda.core.requests.ErrorResponse#UNKNOWN_CHANNEL UNNKOWN_CHANNEL}
2281+
* <br>One of the channels has been deleted before the completion of the task.</li>
2282+
*
2283+
* <li>{@link net.dv8tion.jda.core.requests.ErrorResponse#MISSING_ACCESS MISSING_ACCESS}
2284+
* <br>The currently logged in account was removed from the Guild.</li>
2285+
* </ul>
2286+
*
2287+
* @param category
2288+
* The {@link net.dv8tion.jda.core.entities.Category Category} to order
2289+
* {@link net.dv8tion.jda.core.entities.VoiceChannel VoiceChannels} from.
2290+
*
2291+
* @return {@link net.dv8tion.jda.core.requests.restaction.order.CategoryOrderAction CategoryOrderAction} - Type: {@link net.dv8tion.jda.core.entities.VoiceChannel VoiceChannels}
2292+
*/
2293+
@CheckReturnValue
2294+
public CategoryOrderAction<VoiceChannel> modifyVoiceChannelPositions(Category category)
2295+
{
2296+
Checks.notNull(category, "Category");
2297+
checkGuild(category.getGuild(), "Category");
2298+
return new CategoryOrderAction<>(category, ChannelType.VOICE);
2299+
}
2300+
22322301
/**
22332302
* Modifies the positional order of {@link net.dv8tion.jda.core.entities.Guild#getRoles() Guild.getRoles()}
22342303
* using a specific {@link net.dv8tion.jda.core.requests.RestAction RestAction} extension to allow moving Roles

‎src/main/java/net/dv8tion/jda/core/requests/restaction/order/CategoryOrderAction.java

Lines changed: 106 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,106 @@
1+
/*
2+
* Copyright 2015-2018 Austin Keener & Michael Ritter & Florian Spieß
3+
*
4+
* Licensed under the Apache License, Version 2.0 (the "License");
5+
* you may not use this file except in compliance with the License.
6+
* You may obtain a copy of the License at
7+
*
8+
* http://www.apache.org/licenses/LICENSE-2.0
9+
*
10+
* Unless required by applicable law or agreed to in writing, software
11+
* distributed under the License is distributed on an "AS IS" BASIS,
12+
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13+
* See the License for the specific language governing permissions and
14+
* limitations under the License.
15+
*/
16+
17+
package net.dv8tion.jda.core.requests.restaction.order;
18+
19+
import net.dv8tion.jda.core.entities.Category;
20+
import net.dv8tion.jda.core.entities.Channel;
21+
import net.dv8tion.jda.core.entities.ChannelType;
22+
import net.dv8tion.jda.core.utils.Checks;
23+
24+
import javax.annotation.Nonnull;
25+
import java.util.Collection;
26+
27+
/**
28+
* An extension of {@link net.dv8tion.jda.core.requests.restaction.order.ChannelOrderAction ChannelOrderAction} with
29+
* similar functionality, but constrained to the bounds of a single {@link net.dv8tion.jda.core.entities.Category Category}.
30+
* <br>To apply the changes you must finish the {@link net.dv8tion.jda.core.requests.RestAction RestAction}.
31+
*
32+
* <p>Before you can use any of the {@code move} methods
33+
* you must use either {@link #selectPosition(Object) selectPosition(Channel)} or {@link #selectPosition(int)}!
34+
*
35+
* @param <T>
36+
* The type of {@link net.dv8tion.jda.core.entities.Channel Channel} to move
37+
* using this CategoryOrderAction, either {@link net.dv8tion.jda.core.entities.TextChannel TextChannel},
38+
* or {@link net.dv8tion.jda.core.entities.VoiceChannel VoiceChannel}.
39+
*
40+
* @author Kaidan Gustave
41+
*/
42+
public class CategoryOrderAction<T extends Channel> extends ChannelOrderAction<T>
43+
{
44+
protected final Category category;
45+
46+
/**
47+
* Creates a new CategoryOrderAction for the specified {@link net.dv8tion.jda.core.entities.Category Category}
48+
*
49+
* @param category
50+
* The target {@link net.dv8tion.jda.core.entities.Category Category}
51+
* which the new CategoryOrderAction will order channels from.
52+
* @param type
53+
* The {@link net.dv8tion.jda.core.entities.ChannelType ChannelType} that
54+
* matches the returning value of {@link net.dv8tion.jda.core.entities.Channel#getType() Channel#getType()}
55+
* for the generic {@link net.dv8tion.jda.core.entities.Channel Channel} type {@code T}.
56+
*
57+
* @throws java.lang.IllegalArgumentException
58+
* If the {@code ChannelType} is not one that can be retrieved from a {@code Category}.
59+
* Currently the only two allowed are {@link ChannelType#TEXT} and {@link ChannelType#VOICE}.
60+
*/
61+
@SuppressWarnings("unchecked")
62+
public CategoryOrderAction(Category category, ChannelType type)
63+
{
64+
super(category.getGuild(), type, (Collection<T>) getChannelsOfType(category, type));
65+
this.category = category;
66+
}
67+
68+
/**
69+
* Gets the {@link net.dv8tion.jda.core.entities.Category Category}
70+
* controlled by this CategoryOrderAction.
71+
*
72+
* @return The {@link net.dv8tion.jda.core.entities.Category Category}
73+
* of this CategoryOrderAction.
74+
*/
75+
@Nonnull
76+
public Category getCategory()
77+
{
78+
return category;
79+
}
80+
81+
@Override
82+
protected void validateInput(T entity)
83+
{
84+
Checks.notNull(entity, "Provided channel");
85+
Checks.check(getCategory().equals(entity.getParent()), "Provided channel's Category is not this Category!");
86+
Checks.check(orderList.contains(entity), "Provided channel is not in the list of orderable channels!");
87+
}
88+
89+
@Nonnull
90+
private static Collection<? extends Channel> getChannelsOfType(Category category, ChannelType type)
91+
{
92+
Checks.notNull(type, "ChannelType");
93+
Checks.notNull(category, "Category");
94+
// In the event Discord allows a new channel type to be nested in categories,
95+
// supporting them via CategoryOrderAction is just a matter of adding a new case here.
96+
switch(type)
97+
{
98+
case TEXT:
99+
return category.getTextChannels();
100+
case VOICE:
101+
return category.getVoiceChannels();
102+
default:
103+
throw new IllegalArgumentException("Cannot order category with specified channel type " + type);
104+
}
105+
}
106+
}

‎src/main/java/net/dv8tion/jda/core/requests/restaction/order/ChannelOrderAction.java

Lines changed: 62 additions & 24 deletions
Original file line numberDiff line numberDiff line change
@@ -52,36 +52,59 @@ public class ChannelOrderAction<T extends Channel> extends OrderAction<T, Channe
5252
/**
5353
* Creates a new ChannelOrderAction instance
5454
*
55-
* @param guild
56-
* The target {@link net.dv8tion.jda.core.entities.Guild Guild}
57-
* of which to order the channels defined by the specified type
58-
* @param type
59-
* The {@link net.dv8tion.jda.core.entities.ChannelType ChannelType} corresponding
60-
* to the generic type of {@link net.dv8tion.jda.core.entities.Channel Channel} which
61-
* defines the type of channel that will be ordered
55+
* @param guild
56+
* The target {@link net.dv8tion.jda.core.entities.Guild Guild}
57+
* of which to order the channels defined by the specified type
58+
* @param type
59+
* The {@link net.dv8tion.jda.core.entities.ChannelType ChannelType} corresponding
60+
* to the generic type of {@link net.dv8tion.jda.core.entities.Channel Channel} which
61+
* defines the type of channel that will be ordered.
62+
*
63+
* @throws java.lang.IllegalArgumentException
64+
* If one of the specified Guild has no channels of the ChannelType.
6265
*/
66+
@SuppressWarnings("unchecked")
6367
public ChannelOrderAction(Guild guild, ChannelType type)
68+
{
69+
this(guild, type, (Collection<T>) getChannelsOfType(guild, type));
70+
}
71+
72+
/**
73+
* Creates a new ChannelOrderAction instance using the provided
74+
* {@link net.dv8tion.jda.core.entities.Guild Guild}, as well as the provided
75+
* list of {@link net.dv8tion.jda.core.entities.Channel Channels}.
76+
*
77+
* @param guild
78+
* The target {@link net.dv8tion.jda.core.entities.Guild Guild}
79+
* of which to order the channels defined by the specified type
80+
* @param type
81+
* The {@link net.dv8tion.jda.core.entities.ChannelType ChannelType} corresponding
82+
* to the generic type of {@link net.dv8tion.jda.core.entities.Channel Channel} which
83+
* defines the type of channel that will be ordered.
84+
* @param channels
85+
* The {@link net.dv8tion.jda.core.entities.Channel Channels} to order, all of which
86+
* are on the same Guild specified, and all of which are of the same generic type of Channel
87+
* corresponding to the the ChannelType specified.
88+
*
89+
* @throws java.lang.IllegalArgumentException
90+
* If the channels are {@code null}, an empty collection,
91+
* or any of them do not have the same ChannelType as the one
92+
* provided.
93+
*/
94+
public ChannelOrderAction(Guild guild, ChannelType type, Collection<T> channels)
6495
{
6596
super(guild.getJDA(), Route.Guilds.MODIFY_CHANNELS.compile(guild.getId()));
97+
98+
Checks.notNull(channels, "Channels to order");
99+
Checks.notEmpty(channels, "Channels to order");
100+
Checks.check(channels.stream().allMatch(c -> guild.equals(c.getGuild())),
101+
"One or more channels are not from the correct guild");
102+
Checks.check(channels.stream().allMatch(c -> c.getType().equals(type)),
103+
"One or more channels did not match the expected type of " + type.name());
104+
66105
this.guild = guild;
67106
this.type = type;
68-
69-
Collection chans;
70-
switch (type)
71-
{
72-
case TEXT:
73-
chans = guild.getTextChannels();
74-
break;
75-
case VOICE:
76-
chans = guild.getVoiceChannels();
77-
break;
78-
case CATEGORY:
79-
chans = guild.getCategories();
80-
break;
81-
default:
82-
throw new IllegalArgumentException("Cannot order specified channel type " + type);
83-
}
84-
this.orderList.addAll(chans);
107+
this.orderList.addAll(channels);
85108
}
86109

87110
/**
@@ -130,4 +153,19 @@ protected void validateInput(T entity)
130153
Checks.check(entity.getGuild().equals(guild), "Provided channel is not from this Guild!");
131154
Checks.check(orderList.contains(entity), "Provided channel is not in the list of orderable channels!");
132155
}
156+
157+
private static Collection<? extends Channel> getChannelsOfType(Guild guild, ChannelType type)
158+
{
159+
switch(type)
160+
{
161+
case TEXT:
162+
return guild.getTextChannels();
163+
case VOICE:
164+
return guild.getVoiceChannels();
165+
case CATEGORY:
166+
return guild.getCategories();
167+
default:
168+
throw new IllegalArgumentException("Cannot order specified channel type " + type);
169+
}
170+
}
133171
}

‎src/main/java/net/dv8tion/jda/core/requests/restaction/order/package-info.java

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -19,6 +19,7 @@
1919
* specifically designed to change the order of discord entities.
2020
* <br>Such as:
2121
* <ul>
22+
* <li>{@link net.dv8tion.jda.core.requests.restaction.order.CategoryOrderAction Categories}</li>
2223
* <li>{@link net.dv8tion.jda.core.requests.restaction.order.ChannelOrderAction Channels}</li>
2324
* <li>{@link net.dv8tion.jda.core.requests.restaction.order.RoleOrderAction Roles}</li>
2425
* </ul>

0 commit comments

Comments
 (0)