Using an API

Ok, so I want to use the Cofhlib API, but I have to idea where to actually *put* the API. I am using eclipse and have my mod set up there, so do I just need to extract the API into eclipse? Also I re-set up my dev enviroment when updating my forge, and instead of putting things into a hiearchy, eclipse now lists all packages on the same level and displays them as mod.stuff.morestuff, and all the minecraft packages are the same way, they are all listed as net.minecraft.whatever, which makes it nigh impossible to read or find where things are easily. Sorry for probobly very nooby questions, thanks for all the help.

In case it is a .jar file just put it in a (new) /libs folder in your forge-src folder and import it as a Library. You should be able to access its classes.

in src/main/java add cofh/api

i am currently using the redstone flux api so i have src/main/java/cofh/api/energy and in energy i have all of the api classes

aren't api classes supposed to be included in your mod?

You are using the cofh api? How are you doing that, I am trying to but I can not find any download for the api, only the whole cofh core, and it downloads as a zip file, and I have trouble importing the zip and adding it to my build path, as it doesnt show any of the source. I succesfully installed the IC2 api as it ships as a jar.  How do I go about getting the correct stuff into my workspace for implementing?

Edit:I figured it out and found a CofhLib Jar. Thanks for everyone thats helped.

go here https://github.com/CoFH/RedstoneFlux-API

download the zip and extract it.

I think people often get confused about what an API is.  I get confused about it too, but here is my understanding (feel free to correct me).

Normally after compilation and obfuscation a Java mod's functionality isn't really accessible in a human-readable and accessible way. However, people making a mod can choose to expose functionality as an API by constructing their build (I think you can identify API code in the build.gradle if you're creating an API) such that portions are not obfuscated and can be referenced by their original method name.

The trick then is to make your dev environment "know about" this API so that when you use the API methods in your code there isn't any error.  I think there may be two ways -- you can bring the source over but segregate it as required code that doesn't get built into your mod (I think that is what diesieben07 is suggesting above), or you can actually bring the actual mod into your run location so it is accessed similar to how it will be  when you mod is actually published.

What you don't want to do is to bring their source code into your mod.  Yes you want Eclipse to recognize the methods from the API, but that should be like other libraries instead of actually part of your code.

I don't know all the details to do the above right, but that is the general concept.  You might want to check out CoolAlias' tutorial on APIs: http://www.minecraftforum.net/topic/2496232-tutorial-modding-with-apis/

maby im missing something but all of the mods i have looked at include the apis they use e.g. Extra utills uses the the cofh energy api and the api is included in the extra utills jar.

Also not including the api would make your mod dependent on the mod it belongs wouldn't it?

I think people are confusing "using open source code" with "using an API".  If someone writes an "API" but then gives out the open source code for it, you certainly are allowed to use it.  But that is just copying code, not using an API.

An API is an agreed upon set of calls between two independently developed pieces of code. 

Also not including the api would make your mod dependent on the mod it belongs wouldn't it?

That's the whole point.  You want to take advantage of the other developers' effort by depending on it.  Imagine I made a mod that did some cool world generation and had and API called generateCoolWorld().  You would use my mod (required dependency) and call that method.  But I could independently keep improving what that does -- maybe fix bugs, or make it even cooler world.  You could drop in any version of my mod and the API would be there for you -- the API is like a "contract" or standard.  You should never have to re-build your mod because I fixed a bug in my API.  You just update my mod instead.

There is nothing wrong with using open source code, but if you're building it then I'm pretty sure it isn't an "API".

If your are including an API because you want a soft-dependency (integration if the mod is present, otherwise just don't integrate) you are doing it wrong. Use the Annotations in the Optional class from FML. They allow you to handle this without including the API code.

Yes, I should have mentioned that.  Here is tutorial on @Optional annotation.  http://minalien.com/minecraft-forge-feature-spotlight-optional-annotation/

Ok i must ask is an interface considered an api? because the redstone flux api dosnt contain any methods just a set of interfaces.

Edit: i just realized that was a stupid question "Application Programming Interface"

maby im confused because the redstone flux api isnt specifically designed to allow mods to interact with Thermal Expansion it allows any mod to interact with any other mod using the api even if there are no cofh mods installed.

I guess i will just have to do some research and try to wrap my head around it starting with the links you provided.

Edit:

There is nothing wrong with using open source code, but if you're building it then I'm pretty sure it isn't an "API".

What do you mean by "building" I am i am implementing the apis interfaces

If your are including an API because you want a soft-dependency (integration if the mod is present, otherwise just don't integrate) you are doing it wrong. Use the Annotations in the Optional class from FML. They allow you to handle this without including the API code.

I am using is as the power system for my mod and it dose not in any way dependent on any other mod but it wont function without the api so i am dependent on the api itself not the mod it belongs to.

Ok i must ask is an interface considered an api? because the redstone flux api dosnt contain any methods just a set of interfaces.

 

Edit: i just realized that was a stupid question "Application Programming Interface"

This is kinda a complicated question.  As diesieben07 indicates, the word "interface" can mean different things.  In Java it specifically means a set of public unimplemented methods (someday soon Java will support "default" methods in interfaces allowing some implementation) that enforces compliance on those classes that implement it.

The Java interfaces are mostly intended for enforcing compliance within an internal development team.  For example, if I had a team of software coders working on something I could define the interfaces for them to implement and then they would go off an implement them and I would be sure that the result would have the methods I expect so I could assign another software developer to write code that calls those interfaces. 

There is a secondary use of Java interfaces in helping provide "multiple inheritance".  This is because Java allows you to test instanceof for interfaces.  You can only extend one class, but you can implement multiple interfaces.  So if I wanted to group a bunch of classes that were not extending the same parent class I could define an empty interface and have all the classes implement it and then I could treat them all as instances of that interface.  Not sure if you know what I mean, but I do find this useful sometimes.

An API is usually a bit more "external".  It is telling other people how to access the functionality and resources of your code.  But you might have no interaction with those people at all.  You just publish your compiled code and a documented API and they can use it how they want.

I'm not entirely sure why someone would put a Java interface in an API.  It is not directly callable because the interface isn't implemented.  It can be used to allow the mod with the API to "discover" and use your classes though.  For example, imagine that there was a mod that wanted to add sea life entities to Minecraft and they wanted to be aware if your mod also has sea life entities.  Then the API could provide a Java interface for sea life, you could implement that interface in your seal life entity classes, and in their mod whenever they tested for instanceof they would also see all your entities (and further know how to access them, through the methods the interface forces you to implement).

Not sure if that is entirely clear.  But I would say that generally a Java interface is more about internal developers working together on the same code base, and an API is about external developers being able to interact with your code product.

Ok so i understood most of what you just said and a lot of it i already knew from the java tutorials i have read.

It seems to me from everything you have told me the Redstone flux api isnt like most apis its just a universal energy system that mods can implement in order to be compatible with each other.

Ok so i understood most of what you just said and a lot of it i already knew from the java tutorials i have read.

It seems to me from everything you have told me the Redstone flux api isnt like most apis its just a universal energy system that mods can implement in order to be compatible with each other.

Basically if I want my mod to work with yours I can choose to:

1) just say "hey can you make some deobfuscated methods that we agree on?"  No Java interface but just trust you'll implement the methods as agreed.

b) say "I'll expose an deobfuscated API in my obfuscated mod that exposes a Java interface that you can implement (without needing source)"

z) say "Here's source code for a Java interface that I hope you expose as a deobfuscated API in your obfuscated mod."

All three methods can work, but are just different perspectives on the same problem.  Sounds like Redstone is taking the third approach.