From fa7da0536f30c4f435f9757c0b46348a1136e594 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Florian=20N=C3=BCcke?= Date: Tue, 11 Mar 2014 12:44:19 +0100 Subject: [PATCH] added some more jdoc to api; added FluidTankInfo type converter; made robot interface extend rotatable --- src/main/java/li/cil/oc/api/CreativeTab.java | 4 +- src/main/java/li/cil/oc/api/Driver.java | 9 +- src/main/java/li/cil/oc/api/Machine.java | 12 +- .../java/li/cil/oc/api/detail/Builder.java | 125 ++++++++++++++++-- .../li/cil/oc/api/detail/package-info.java | 6 + .../li/cil/oc/api/driver/package-info.java | 7 + .../java/li/cil/oc/api/fs/package-info.java | 16 +++ .../java/li/cil/oc/api/machine/Robot.java | 3 +- .../li/cil/oc/api/machine/package-info.java | 19 +++ src/main/java/li/cil/oc/api/package-info.java | 2 +- src/main/scala/li/cil/oc/common/Proxy.scala | 7 +- .../driver/converter/FluidTankInfo.scala | 25 ++++ .../server/driver/converter/ItemStack.scala | 3 +- 13 files changed, 215 insertions(+), 23 deletions(-) create mode 100644 src/main/java/li/cil/oc/api/detail/package-info.java create mode 100644 src/main/java/li/cil/oc/api/driver/package-info.java create mode 100644 src/main/java/li/cil/oc/api/fs/package-info.java create mode 100644 src/main/java/li/cil/oc/api/machine/package-info.java create mode 100644 src/main/scala/li/cil/oc/server/driver/converter/FluidTankInfo.scala diff --git a/src/main/java/li/cil/oc/api/CreativeTab.java b/src/main/java/li/cil/oc/api/CreativeTab.java index f3060d30a..52e1afabe 100644 --- a/src/main/java/li/cil/oc/api/CreativeTab.java +++ b/src/main/java/li/cil/oc/api/CreativeTab.java @@ -9,7 +9,9 @@ public final class CreativeTab { /** * The creative tab used by OpenComputers. *

- * Changed to the actual tab if OC is present. + * Changed to the actual tab if OC is present. Preferably you do + * not try to access this anyway when OpenComputers isn't + * present (don't ship the API in your mod), so don't rely on this! */ public static CreativeTabs Instance = CreativeTabs.tabRedstone; diff --git a/src/main/java/li/cil/oc/api/Driver.java b/src/main/java/li/cil/oc/api/Driver.java index 64e88ebfa..6b1398641 100644 --- a/src/main/java/li/cil/oc/api/Driver.java +++ b/src/main/java/li/cil/oc/api/Driver.java @@ -32,7 +32,8 @@ public final class Driver { * @param driver the driver to register. */ public static void add(final Block driver) { - if (instance != null) instance.add(driver); + if (instance != null) + instance.add(driver); } /** @@ -47,7 +48,8 @@ public final class Driver { * @param driver the driver to register. */ public static void add(final Item driver) { - if (instance != null) instance.add(driver); + if (instance != null) + instance.add(driver); } /** @@ -62,7 +64,8 @@ public final class Driver { * @param converter the converter to register. */ public static void add(final Converter converter) { - if (instance != null) instance.add(converter); + if (instance != null) + instance.add(converter); } // ----------------------------------------------------------------------- // diff --git a/src/main/java/li/cil/oc/api/Machine.java b/src/main/java/li/cil/oc/api/Machine.java index d11a54b4d..8a6d3bf53 100644 --- a/src/main/java/li/cil/oc/api/Machine.java +++ b/src/main/java/li/cil/oc/api/Machine.java @@ -35,7 +35,8 @@ public final class Machine { * @param architecture the architecture to register. */ public static void add(Class architecture) { - if (instance != null) instance.add(architecture); + if (instance != null) + instance.add(architecture); } /** @@ -71,7 +72,8 @@ public final class Machine { * until it also created a new machine using that architecture. */ public static Iterable> architectures() { - if (instance != null) return instance.architectures(); + if (instance != null) + return instance.architectures(); return Collections.emptyList(); } @@ -87,7 +89,8 @@ public final class Machine { * @throws IllegalArgumentException if the specified architecture is invalid. */ public static li.cil.oc.api.machine.Machine create(Owner owner, Class architecture) { - if (instance != null) return instance.create(owner, architecture); + if (instance != null) + return instance.create(owner, architecture); return null; } @@ -101,7 +104,8 @@ public final class Machine { * @return the newly created machine. */ public static li.cil.oc.api.machine.Machine create(Owner owner) { - if (instance != null) return instance.create(owner, LuaArchitecture); + if (instance != null) + return instance.create(owner, LuaArchitecture); return null; } diff --git a/src/main/java/li/cil/oc/api/detail/Builder.java b/src/main/java/li/cil/oc/api/detail/Builder.java index d4672f38f..f644282de 100644 --- a/src/main/java/li/cil/oc/api/detail/Builder.java +++ b/src/main/java/li/cil/oc/api/detail/Builder.java @@ -8,30 +8,139 @@ import li.cil.oc.api.network.*; * @param the type of the node created by this builder. */ public interface Builder { + /** + * Finalizes the construction of the node. + *

+ * This performs the actual creation of the node, initializes it to the + * settings defined by the current builder and returns it. + * + * @return the final node. + */ T create(); + /** + * Builder for basic nodes. These nodes merely allow network access and + * take on no special role. + */ public static interface NodeBuilder extends Builder { - ComponentBuilder withComponent(final String name); + /** + * Makes the node a component. + *

+ * Nodes that are components can be accessed from computers, methods + * declared in them marked using the {@link Callback} annotation can + * be invoked from computers that can see the component. + * + * @param name the name of the component. + * @param visibility the visibility of the component. + * @return a builder for a node that is also a component. + * @see li.cil.oc.api.network.Component + */ + ComponentBuilder withComponent(String name, Visibility visibility); - ComponentBuilder withComponent(final String name, final Visibility visibility); + /** + * Makes the node a component. + *

+ * Like {@link #withComponent(String, Visibility)}, but with a default + * visibility set to the reachability of the node. + * + * @param name the name of the component. + * @return a builder for a node that is also a component. + * @see li.cil.oc.api.network.Component + */ + ComponentBuilder withComponent(String name); + /** + * Makes the node a connector. + *

+ * A connector node can feed power into the network and extract power + * from the network. This is used both for passive energy drain (such + * as running screens and computers) and for active power consumption + * (such as wireless message sending or robot actions). + * + * @param bufferSize the size of the local energy buffer. + * @return a builder for a node that is also a connector. + * @see li.cil.oc.api.network.Connector + */ + ConnectorBuilder withConnector(double bufferSize); + + /** + * Makes the node a connector. + *

+ * Like {@link #withConnector(double)}, but with a default buffer size + * of zero. + * + * @return a builder for a node that is also a connector. + * @see li.cil.oc.api.network.Connector + */ ConnectorBuilder withConnector(); - - ConnectorBuilder withConnector(final double bufferSize); } + /** + * Builder for component nodes. These node can be interacted with from + * computers in the same network, that can see the component. + */ public static interface ComponentBuilder extends Builder { + /** + * Makes the node a connector. + *

+ * A connector node can feed power into the network and extract power + * from the network. This is used both for passive energy drain (such + * as running screens and computers) and for active power consumption + * (such as wireless message sending or robot actions). + * + * @param bufferSize the size of the local energy buffer. + * @return a builder for a node that is also a connector. + * @see li.cil.oc.api.network.Connector + */ + ComponentConnectorBuilder withConnector(double bufferSize); + + /** + * Makes the node a connector. + *

+ * Like {@link #withConnector(double)}, but with a default buffer size + * of zero. + * + * @return a builder for a node that is also a connector. + * @see li.cil.oc.api.network.Connector + */ ComponentConnectorBuilder withConnector(); - - ComponentConnectorBuilder withConnector(final double bufferSize); } + /** + * Builder for connector nodes. These nodes can interact with the energy + * stored in the network, i.e. increase or reduce it. + */ public static interface ConnectorBuilder extends Builder { - ComponentConnectorBuilder withComponent(final String name); + /** + * Makes the node a component. + *

+ * Nodes that are components can be accessed from computers, methods + * declared in them marked using the {@link Callback} annotation can + * be invoked from computers that can see the component. + * + * @param name the name of the component. + * @param visibility the visibility of the component. + * @return a builder for a node that is also a component. + * @see li.cil.oc.api.network.Component + */ + ComponentConnectorBuilder withComponent(String name, Visibility visibility); - ComponentConnectorBuilder withComponent(final String name, final Visibility visibility); + /** + * Makes the node a component. + *

+ * Like {@link #withComponent(String, Visibility)}, but with a default + * visibility set to the reachability of the node. + * + * @param name the name of the component. + * @return a builder for a node that is also a component. + * @see li.cil.oc.api.network.Component + */ + ComponentConnectorBuilder withComponent(String name); } + /** + * Builder for nodes that are both component and connector node. + */ public static interface ComponentConnectorBuilder extends Builder { } } diff --git a/src/main/java/li/cil/oc/api/detail/package-info.java b/src/main/java/li/cil/oc/api/detail/package-info.java new file mode 100644 index 000000000..d33ae2f40 --- /dev/null +++ b/src/main/java/li/cil/oc/api/detail/package-info.java @@ -0,0 +1,6 @@ +/** + * This package contains implementation detail interfaces. You will not have to + * interact with these interfaces directly (except for the Builder), + * and you particularly should not implement these interfaces yourself. + */ +package li.cil.oc.api.detail; \ No newline at end of file diff --git a/src/main/java/li/cil/oc/api/driver/package-info.java b/src/main/java/li/cil/oc/api/driver/package-info.java new file mode 100644 index 000000000..9dcdc933d --- /dev/null +++ b/src/main/java/li/cil/oc/api/driver/package-info.java @@ -0,0 +1,7 @@ +/** + * This package contains driver related interfaces. + *

+ * Drivers are used to add items and third party blocks to the internal network, + * which is mostly used to make components wrapping them available to computers. + */ +package li.cil.oc.api.driver; \ No newline at end of file diff --git a/src/main/java/li/cil/oc/api/fs/package-info.java b/src/main/java/li/cil/oc/api/fs/package-info.java new file mode 100644 index 000000000..1a3d776d0 --- /dev/null +++ b/src/main/java/li/cil/oc/api/fs/package-info.java @@ -0,0 +1,16 @@ +/** + * This package contains interfaces used by the file system implementation. + *

+ * This allows it to add custom file systems that will behave the same as the + * existing ones, particularly that can be used the same from a machine as any + * other. In the case of Lua, for example, this means it can be mounted like + * any other file system, and interacted with without further special handling. + *

+ * You will usually not need to implement these interfaces! + *

+ * Consider using the factory methods in {@link li.cil.oc.api.FileSystem} to + * create file systems and wrapper nodes for these file systems (i.e. nodes + * that can be added as component nodes to the network, so they can be used + * from computers). + */ +package li.cil.oc.api.fs; \ No newline at end of file diff --git a/src/main/java/li/cil/oc/api/machine/Robot.java b/src/main/java/li/cil/oc/api/machine/Robot.java index e14741058..956513357 100644 --- a/src/main/java/li/cil/oc/api/machine/Robot.java +++ b/src/main/java/li/cil/oc/api/machine/Robot.java @@ -1,5 +1,6 @@ package li.cil.oc.api.machine; +import li.cil.oc.api.Rotatable; import net.minecraft.entity.player.EntityPlayer; /** @@ -9,7 +10,7 @@ import net.minecraft.entity.player.EntityPlayer; * case, the robot in question is the tile entity passed to item driver when * asked to create the component's environment. */ -public interface Robot { +public interface Robot extends Rotatable { /** * Returns the fake player used to represent the robot as an entity for * certain actions that require one. diff --git a/src/main/java/li/cil/oc/api/machine/package-info.java b/src/main/java/li/cil/oc/api/machine/package-info.java new file mode 100644 index 000000000..adc4883cb --- /dev/null +++ b/src/main/java/li/cil/oc/api/machine/package-info.java @@ -0,0 +1,19 @@ +/** + * This package provides low level machine access. + *

+ * Using the {@link li.cil.oc.api.Machine} class, you can create new machine + * instances, i.e. essentially computer "cores", that will run code. This allows + * you to implement your own computer blocks. Or robots. Or whatever you come up + * with. + *

+ * The interfaces in here also allow you to implement an arbitrary new + * {@link li.cil.oc.api.machine.Architecture}, which can then be used when + * creating a new {@link li.cil.oc.api.machine.Machine} using the factory + * methods in {@link li.cil.oc.api.Machine}. An architecture could be a custom + * language interpreter, or a full blown hardware emulator for old microchips. + *

+ * There are also a couple of interfaces in here that are not meant to be + * implemented, but merely to allow accessing some mod internals in a regulated + * fashion, such as {@link li.cil.oc.api.machine.Robot}. + */ +package li.cil.oc.api.machine; \ No newline at end of file diff --git a/src/main/java/li/cil/oc/api/package-info.java b/src/main/java/li/cil/oc/api/package-info.java index 974733598..c3e1cf8c9 100644 --- a/src/main/java/li/cil/oc/api/package-info.java +++ b/src/main/java/li/cil/oc/api/package-info.java @@ -37,5 +37,5 @@ @cpw.mods.fml.common.API( owner = "OpenComputers|Core", provides = "OpenComputersAPI", - apiVersion = "1.4.8") + apiVersion = "1.4.9") package li.cil.oc.api; \ No newline at end of file diff --git a/src/main/scala/li/cil/oc/common/Proxy.scala b/src/main/scala/li/cil/oc/common/Proxy.scala index 90705b0ce..aa3020558 100644 --- a/src/main/scala/li/cil/oc/common/Proxy.scala +++ b/src/main/scala/li/cil/oc/common/Proxy.scala @@ -19,7 +19,7 @@ import li.cil.oc.util.LuaStateFactory import net.minecraftforge.common.MinecraftForge class Proxy { - def preInit(e: FMLPreInitializationEvent): Unit = { + def preInit(e: FMLPreInitializationEvent) { Settings.load(e.getSuggestedConfigurationFile) Blocks.init() @@ -44,7 +44,7 @@ class Proxy { Settings.resourceDomain + "/lua/rom") } - def init(e: FMLInitializationEvent): Unit = { + def init(e: FMLInitializationEvent) { api.Driver.add(driver.item.AbstractBusCard) api.Driver.add(driver.item.FileSystem) api.Driver.add(driver.item.GraphicsCard) @@ -61,6 +61,7 @@ class Proxy { api.Driver.add(driver.item.UpgradeSolarGenerator) api.Driver.add(driver.item.WirelessNetworkCard) + api.Driver.add(driver.converter.FluidTankInfo) api.Driver.add(driver.converter.ItemStack) Recipes.init() @@ -69,7 +70,7 @@ class Proxy { Loot.init() } - def postInit(e: FMLPostInitializationEvent): Unit = { + def postInit(e: FMLPostInitializationEvent) { // Don't allow driver registration after this point, to avoid issues. driver.Registry.locked = true diff --git a/src/main/scala/li/cil/oc/server/driver/converter/FluidTankInfo.scala b/src/main/scala/li/cil/oc/server/driver/converter/FluidTankInfo.scala new file mode 100644 index 000000000..799c9d666 --- /dev/null +++ b/src/main/scala/li/cil/oc/server/driver/converter/FluidTankInfo.scala @@ -0,0 +1,25 @@ +package li.cil.oc.server.driver.converter + +import java.util +import li.cil.oc.api +import net.minecraftforge.fluids +import scala.collection.convert.WrapAsScala._ + +object FluidTankInfo extends api.driver.Converter { + override def convert(value: AnyRef, output: util.Map[AnyRef, AnyRef]) = + value match { + case tankInfo: fluids.FluidTankInfo => + output += "capacity" -> Int.box(tankInfo.capacity) + if (tankInfo.fluid != null) { + output += "amount" -> Int.box(tankInfo.fluid.amount) + output += "id" -> Int.box(tankInfo.fluid.fluidID) + val fluid = tankInfo.fluid.getFluid + if (fluid != null) { + output += "name" -> fluid.getName + output += "label" -> fluid.getLocalizedName + } + } + else output += "amount" -> Int.box(0) + case _ => + } +} diff --git a/src/main/scala/li/cil/oc/server/driver/converter/ItemStack.scala b/src/main/scala/li/cil/oc/server/driver/converter/ItemStack.scala index 8bfa14042..16263fbc2 100644 --- a/src/main/scala/li/cil/oc/server/driver/converter/ItemStack.scala +++ b/src/main/scala/li/cil/oc/server/driver/converter/ItemStack.scala @@ -6,7 +6,7 @@ import net.minecraft.item import scala.collection.convert.WrapAsScala._ object ItemStack extends api.driver.Converter { - override def convert(value: AnyRef, output: util.Map[AnyRef, AnyRef]) = { + override def convert(value: AnyRef, output: util.Map[AnyRef, AnyRef]) = value match { case stack: item.ItemStack => output += "id" -> Int.box(stack.itemID) @@ -21,5 +21,4 @@ object ItemStack extends api.driver.Converter { } case _ => } - } }