Skip to content

Commit 10ded26

Browse files
dmulloy2dmulloy2
committed
Documentation improvements
1 parent 74adaba commit 10ded26

File tree

14 files changed

+262
-169
lines changed

14 files changed

+262
-169
lines changed

‎modules/API/src/main/java/com/comphenix/protocol/ProtocolLibrary.java‎

Lines changed: 70 additions & 22 deletions
Original file line numberDiff line numberDiff line change
@@ -1,27 +1,43 @@
1+
/**
2+
* ProtocolLib - Bukkit server library that allows access to the Minecraft protocol.
3+
* Copyright (C) 2016 dmulloy2
4+
*
5+
* This program is free software; you can redistribute it and/or modify it under the terms of the
6+
* GNU General Public License as published by the Free Software Foundation; either version 2 of
7+
* the License, or (at your option) any later version.
8+
*
9+
* This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY;
10+
* without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
11+
* See the GNU General Public License for more details.
12+
*
13+
* You should have received a copy of the GNU General Public License along with this program;
14+
* if not, write to the Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA
15+
* 02111-1307 USA
16+
*/
117
package com.comphenix.protocol;
218

3-
import java.text.MessageFormat;
419
import java.util.Arrays;
520
import java.util.List;
6-
import java.util.logging.Level;
721

22+
import org.apache.commons.lang.Validate;
823
import org.bukkit.plugin.Plugin;
924

1025
import com.comphenix.protocol.error.BasicErrorReporter;
1126
import com.comphenix.protocol.error.ErrorReporter;
1227
import com.google.common.util.concurrent.ListeningScheduledExecutorService;
1328

29+
/**
30+
* The main entry point for ProtocolLib.
31+
* @author dmulloy2
32+
*/
1433
public class ProtocolLibrary {
15-
public static final long MILLI_PER_SECOND = 1000;
16-
public static final List<String> INCOMPATIBLE = Arrays.asList("TagAPI");
17-
1834
/**
1935
* The minimum version ProtocolLib has been tested with.
2036
*/
2137
public static final String MINIMUM_MINECRAFT_VERSION = "1.9";
2238

2339
/**
24-
* The maximum version ProtocolLib has been tested with,
40+
* The maximum version ProtocolLib has been tested with.
2541
*/
2642
public static final String MAXIMUM_MINECRAFT_VERSION = "1.9";
2743

@@ -30,6 +46,11 @@ public class ProtocolLibrary {
3046
*/
3147
public static final String MINECRAFT_LAST_RELEASE_DATE = "2016-02-29";
3248

49+
/**
50+
* Plugins that are currently incompatible with ProtocolLib.
51+
*/
52+
public static final List<String> INCOMPATIBLE = Arrays.asList("TagAPI");
53+
3354
private static Plugin plugin;
3455
private static ProtocolConfig config;
3556
private static ProtocolManager manager;
@@ -39,58 +60,85 @@ public class ProtocolLibrary {
3960
private static ListeningScheduledExecutorService executorSync;
4061

4162
private static boolean updatesDisabled;
63+
private static boolean initialized;
4264

4365
protected static void init(Plugin plugin, ProtocolConfig config, ProtocolManager manager, ErrorReporter reporter,
4466
ListeningScheduledExecutorService executorAsync, ListeningScheduledExecutorService executorSync) {
67+
Validate.isTrue(!initialized, "ProtocolLib has already been initialized.");
4568
ProtocolLibrary.plugin = plugin;
4669
ProtocolLibrary.config = config;
4770
ProtocolLibrary.manager = manager;
4871
ProtocolLibrary.reporter = reporter;
4972
ProtocolLibrary.executorAsync = executorAsync;
5073
ProtocolLibrary.executorSync = executorSync;
74+
ProtocolLogger.init(plugin);
75+
initialized = true;
5176
}
5277

78+
/**
79+
* Gets the ProtocolLib plugin instance.
80+
* @return The plugin instance
81+
*/
5382
public static Plugin getPlugin() {
5483
return plugin;
5584
}
5685

86+
/**
87+
* Gets ProtocolLib's configuration
88+
* @return The config
89+
*/
5790
public static ProtocolConfig getConfig() {
5891
return config;
5992
}
6093

94+
/**
95+
* Retrieves the packet protocol manager.
96+
* @return Packet protocol manager
97+
*/
6198
public static ProtocolManager getProtocolManager() {
6299
return manager;
63100
}
64101

102+
/**
103+
* Retrieve the current error reporter.
104+
* @return Current error reporter.
105+
*/
65106
public static ErrorReporter getErrorReporter() {
66107
return reporter;
67108
}
68109

69-
public static void disableUpdates() {
70-
updatesDisabled = true;
71-
}
72-
73-
public static boolean updatesDisabled() {
74-
return updatesDisabled;
75-
}
76-
110+
/**
111+
* Retrieve an executor service for performing asynchronous tasks on the behalf of ProtocolLib.
112+
* <p>
113+
* Note that this service is NULL if ProtocolLib has not been initialized yet.
114+
* @return The executor service, or NULL.
115+
*/
77116
public static ListeningScheduledExecutorService getExecutorAsync() {
78117
return executorAsync;
79118
}
80119

120+
/**
121+
* Retrieve an executor service for performing synchronous tasks (main thread) on the behalf of ProtocolLib.
122+
* <p>
123+
* Note that this service is NULL if ProtocolLib has not been initialized yet.
124+
* @return The executor service, or NULL.
125+
*/
81126
public static ListeningScheduledExecutorService getExecutorSync() {
82127
return executorSync;
83128
}
84129

85-
public static void log(Level level, String message, Object... args) {
86-
plugin.getLogger().log(level, MessageFormat.format(message, args));
87-
}
88-
89-
public static void log(String message, Object... args) {
90-
log(Level.INFO, message, args);
130+
/**
131+
* Disables the ProtocolLib update checker.
132+
*/
133+
public static void disableUpdates() {
134+
updatesDisabled = true;
91135
}
92136

93-
public static void log(Level level, String message, Throwable ex) {
94-
plugin.getLogger().log(level, message, ex);
137+
/**
138+
* Whether or not updates are currently disabled.
139+
* @return True if it is, false if not
140+
*/
141+
public static boolean updatesDisabled() {
142+
return updatesDisabled;
95143
}
96144
}

‎modules/API/src/main/java/com/comphenix/protocol/ProtocolLogger.java‎

Lines changed: 63 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,63 @@
1+
/**
2+
* ProtocolLib - Bukkit server library that allows access to the Minecraft protocol.
3+
* Copyright (C) 2016 dmulloy2
4+
*
5+
* This program is free software; you can redistribute it and/or modify it under the terms of the
6+
* GNU General Public License as published by the Free Software Foundation; either version 2 of
7+
* the License, or (at your option) any later version.
8+
*
9+
* This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY;
10+
* without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
11+
* See the GNU General Public License for more details.
12+
*
13+
* You should have received a copy of the GNU General Public License along with this program;
14+
* if not, write to the Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA
15+
* 02111-1307 USA
16+
*/
17+
package com.comphenix.protocol;
18+
19+
import java.text.MessageFormat;
20+
import java.util.logging.Level;
21+
import java.util.logging.Logger;
22+
23+
import org.bukkit.plugin.Plugin;
24+
25+
/**
26+
* @author dmulloy2
27+
*/
28+
public class ProtocolLogger {
29+
private static Logger logger;
30+
31+
protected static void init(Plugin plugin) {
32+
ProtocolLogger.logger = plugin.getLogger();
33+
}
34+
35+
/**
36+
* Logs a message to console with a given level.
37+
* @param level Logging level
38+
* @param message Message to log
39+
* @param args Arguments to format in
40+
*/
41+
public static void log(Level level, String message, Object... args) {
42+
logger.log(level, MessageFormat.format(message, args));
43+
}
44+
45+
/**
46+
* Logs a method to console with the INFO level.
47+
* @param message Message to log
48+
* @param args Arguments to format in
49+
*/
50+
public static void log(String message, Object... args) {
51+
log(Level.INFO, message, args);
52+
}
53+
54+
/**
55+
* Logs a message to console with a given level and exception.
56+
* @param level Logging level
57+
* @param message Message to log
58+
* @param ex Exception to log
59+
*/
60+
public static void log(Level level, String message, Throwable ex) {
61+
logger.log(level, message, ex);
62+
}
63+
}

‎modules/API/src/main/java/com/comphenix/protocol/async/AsyncMarker.java‎

Lines changed: 5 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -28,7 +28,7 @@
2828

2929
import com.comphenix.protocol.PacketStream;
3030
import com.comphenix.protocol.PacketType;
31-
import com.comphenix.protocol.ProtocolLibrary;
31+
import com.comphenix.protocol.ProtocolLogger;
3232
import com.comphenix.protocol.events.NetworkMarker;
3333
import com.comphenix.protocol.events.PacketEvent;
3434
import com.comphenix.protocol.injector.PrioritizedListener;
@@ -429,15 +429,17 @@ public boolean isMinecraftAsync(PacketEvent event) throws FieldAccessException {
429429
// Incoming chat packets are async only if they aren't commands
430430
return ! content.startsWith("/");
431431
} else {
432-
ProtocolLibrary.log(Level.WARNING, "Failed to determine contents of incoming chat packet!");
432+
ProtocolLogger.log(Level.WARNING, "Failed to determine contents of incoming chat packet!");
433433
alwaysSync = true;
434434
}
435+
} else if (event.getPacketType() == PacketType.Status.Server.SERVER_INFO) {
436+
return true;
435437
} else {
436438
// TODO: Find more cases of async packets
437439
return false;
438440
}
439441
} else {
440-
ProtocolLibrary.log(Level.INFO, "Could not determine asynchronous state of packets (this can probably be ignored)");
442+
ProtocolLogger.log(Level.INFO, "Could not determine asynchronous state of packets (this can probably be ignored)");
441443
alwaysSync = true;
442444
}
443445
}

‎modules/API/src/main/java/com/comphenix/protocol/error/DetailedErrorReporter.java‎

Lines changed: 6 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -35,7 +35,7 @@
3535
import org.bukkit.Bukkit;
3636
import org.bukkit.plugin.Plugin;
3737

38-
import com.comphenix.protocol.ProtocolLibrary;
38+
import com.comphenix.protocol.ProtocolLogger;
3939
import com.comphenix.protocol.collections.ExpireHashMap;
4040
import com.comphenix.protocol.error.Report.ReportBuilder;
4141
import com.comphenix.protocol.events.PacketAdapter;
@@ -464,13 +464,15 @@ public static String getStringDescription(Object value) {
464464
} else {
465465
try {
466466
if (!apacheCommonsMissing)
467-
return (ToStringBuilder.reflectionToString(value, ToStringStyle.MULTI_LINE_STYLE, false, null));
467+
return ToStringBuilder.reflectionToString(value, ToStringStyle.MULTI_LINE_STYLE, false, null);
468468
} catch (LinkageError ex) {
469469
// Apache is probably missing
470470
apacheCommonsMissing = true;
471-
} catch (Exception e) {
471+
} catch (ThreadDeath | OutOfMemoryError e) {
472+
throw e;
473+
} catch (Throwable ex) {
472474
// Don't use the error logger to log errors in error logging (that could lead to infinite loops)
473-
ProtocolLibrary.log(Level.WARNING, "Cannot convert to a String with Apache: " + e.getMessage());
475+
ProtocolLogger.log(Level.WARNING, "Cannot convert to a String with Apache: " + ex.getMessage());
474476
}
475477

476478
// Use our custom object printer instead

‎modules/ProtocolLib/src/main/java/com/comphenix/protocol/package-info.java‎ renamed to ‎modules/API/src/main/java/com/comphenix/protocol/package-info.java‎

File renamed without changes.

‎modules/API/src/main/java/com/comphenix/protocol/reflect/StructureModifier.java‎

Lines changed: 5 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -27,6 +27,7 @@
2727
import java.util.logging.Level;
2828

2929
import com.comphenix.protocol.ProtocolLibrary;
30+
import com.comphenix.protocol.ProtocolLogger;
3031
import com.comphenix.protocol.error.PluginContext;
3132
import com.comphenix.protocol.reflect.compiler.BackgroundCompiler;
3233
import com.comphenix.protocol.reflect.instances.BannedGenerator;
@@ -198,8 +199,8 @@ public TField read(int fieldIndex) throws FieldAccessException {
198199
} catch (FieldAccessException ex) {
199200
String plugin = PluginContext.getPluginCaller(ex);
200201
if (ProtocolLibrary.INCOMPATIBLE.contains(plugin)) {
201-
ProtocolLibrary.log(Level.WARNING, "Encountered an exception caused by incompatible plugin {0}.", plugin);
202-
ProtocolLibrary.log(Level.WARNING, "It is advised that you remove it.");
202+
ProtocolLogger.log(Level.WARNING, "Encountered an exception caused by incompatible plugin {0}.", plugin);
203+
ProtocolLogger.log(Level.WARNING, "It is advised that you remove it.");
203204
}
204205

205206
throw ex;
@@ -328,8 +329,8 @@ public StructureModifier<TField> write(int fieldIndex, TField value) throws Fiel
328329
} catch (FieldAccessException ex) {
329330
String plugin = PluginContext.getPluginCaller(ex);
330331
if (ProtocolLibrary.INCOMPATIBLE.contains(plugin)) {
331-
ProtocolLibrary.log(Level.WARNING, "Encountered an exception caused by incompatible plugin {0}.", plugin);
332-
ProtocolLibrary.log(Level.WARNING, "It is advised that you remove it.");
332+
ProtocolLogger.log(Level.WARNING, "Encountered an exception caused by incompatible plugin {0}.", plugin);
333+
ProtocolLogger.log(Level.WARNING, "It is advised that you remove it.");
333334
}
334335

335336
throw ex;

‎modules/API/src/main/java/com/comphenix/protocol/reflect/VolatileField.java‎

Lines changed: 2 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -19,7 +19,7 @@
1919

2020
import java.lang.reflect.Field;
2121

22-
import com.comphenix.protocol.ProtocolLibrary;
22+
import com.comphenix.protocol.ProtocolLogger;
2323
import com.comphenix.protocol.reflect.accessors.Accessors;
2424
import com.comphenix.protocol.reflect.accessors.FieldAccessor;
2525
import com.google.common.base.Objects;
@@ -184,8 +184,7 @@ public void revertValue() {
184184
currentSet = false;
185185
} else {
186186
// This can be a bad sign
187-
ProtocolLibrary.log("Unable to switch {0} to {1}. Expected {2}, but got {3}.",
188-
getField().toGenericString(), previous, current, getValue());
187+
ProtocolLogger.log("Unable to switch {0} to {1}. Expected {2}, but got {3}.", getField().toGenericString(), previous, current, getValue());
189188
}
190189
}
191190
}

‎modules/API/src/main/java/com/comphenix/protocol/reflect/instances/DefaultInstances.java‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -26,7 +26,7 @@
2626

2727
import net.sf.cglib.proxy.Enhancer;
2828

29-
import com.comphenix.protocol.ProtocolLibrary;
29+
import com.comphenix.protocol.ProtocolLogger;
3030
import com.google.common.base.Objects;
3131
import com.google.common.collect.ImmutableList;
3232

@@ -284,7 +284,7 @@ private <T> T getDefaultInternal(Class<T> type, List<InstanceProvider> providers
284284

285285
// Did we break the non-null contract?
286286
if (params[i] == null && nonNull) {
287-
ProtocolLibrary.log(Level.WARNING, "Nonnull contract broken.");
287+
ProtocolLogger.log(Level.WARNING, "Nonnull contract broken.");
288288
return null;
289289
}
290290
}

‎modules/API/src/main/java/com/comphenix/protocol/utility/MinecraftReflection.java‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -46,6 +46,7 @@
4646

4747
import com.comphenix.protocol.PacketType;
4848
import com.comphenix.protocol.ProtocolLibrary;
49+
import com.comphenix.protocol.ProtocolLogger;
4950
import com.comphenix.protocol.error.ErrorReporter;
5051
import com.comphenix.protocol.error.Report;
5152
import com.comphenix.protocol.error.ReportType;
@@ -208,7 +209,7 @@ public static String getMinecraftPackage() {
208209
if (MinecraftVersion.SCARY_UPDATE.compareTo(version) <= 0) {
209210
// Just assume R1 - it's probably fine
210211
packageVersion = "v" + version.getMajor() + "_" + version.getMinor() + "_R1";
211-
ProtocolLibrary.log(Level.WARNING, "Assuming package version: " + packageVersion);
212+
ProtocolLogger.log(Level.WARNING, "Assuming package version: " + packageVersion);
212213
}
213214
}
214215

0 commit comments

Comments
 (0)