Closed. This question needs to be more focused. It is not currently accepting answers.
Want to improve this question? Update the question so it focuses on one problem only by editing this post.
Closed 5 years ago.
Improve this question
I just realized from an article in CACM that Doxygen works with Java (and several other languages) too. But Java has already the Javadoc tool. Can someone explain what are the pros and cons of either approach? Are they mutually exclusive? Is there a Maven plugin for Doxygen?
Doxygen has a number of features that JavaDoc does not offer, e.g. the class diagrams for the hierarchies and the cooperation context, more summary pages, optional source-code browsing (cross-linked with the documentation), additional tag support such as #todo on a separate page and it can generate output in TeX and PDF format.It also allows a lot of visual customization.
Since Doxygen supports the standard JavaDoc tags you can run Doxygen on any source code with JavaDoc comments on it. It often can even make sense to run on source code without JavaDoc since the diagrams and source code browsing can help understanding code even without the documentation. And since the JavaDoc tool ignores unknown tags you can even use additional Doxygen tags without breaking JavaDoc generation.
Having said all this I must admit that I haven't used Doxygen for a long time. I tend to rely heavily on my IDE nowadays to provide the same visualization and I usually don't read JavaDoc as HTML pages but import the source files into my IDE so it can generate JavaDoc flyouts and I can jump to the definitions. That's even more powerful than what Doxygen has to offer. If you want to have documentation outside the IDE and are happy to run non-Java tooling then Doxygen is worth a try since it doesn't require any change to your Java code.
I'd only use Doxygen with Java if you're new to Java and you've used Doxygen before, reducing the learning curve you'd experience with javadoc. If you haven't used Doxygen before, I'd stick with javadoc, since it was specifically designed with Java in mind. If you don't know either one, and you work in C++ (or other supported languages) as much as you do Java, Doxygen is a good choice, as you'll be able to use it for both languages.
Both tools are easy to use, with a similar feature set. Both have plugins (or are pre-built in) for NetBeans and Eclipse making it even faster to generate doc. There is a lot of overlap in the comment style used by each, but they're not exactly the same, so it would be difficult to mix them together (you'd have to know the details of both, leaving out any features that are specific to one or the other). I've never used it, but there does seem to be a Maven plugin for Doxygen.
I like the fact that with Doxygen, you can get class diagrams displayed on the same page as the documentation. Also, I like the fact that it links you directly to the source code, if needed. I am not aware if javadoc has these features though.
One big advantage of JavaDocs is that they just work. Everything needed to build and view them is included in the JDK that you already need to have installed for compiling your programs.
Doxygen, on the other hand can be a pain to set up and get working correctly. but if it is set up correctly it should be able to generate PDFs, RTFs, and DocBooks, as well as HTML. The HTML is not organized as well by default as JavaDocs since the index.html brings up a blank page by default. Also, inline classes and static members may need special flags to be included in documentation, and if you want to generate a PDF you may have to deal with hassles of your distribution of Linux not having the needed pdflatex command (e.g. Ubuntu/Mint have had problems recently) so if you just apt-get install it and run you may get a screen full of errors even with a simple program. Compared to the ease of getting javadoc automatically when you install the API, Doxygen setup can be a miserable experience. Once you overcome the hurdles, it should be more flexible in dealing with projects involving more than just java, though.
Related
Closed. This question is opinion-based. It is not currently accepting answers.
Want to improve this question? Update the question so it can be answered with facts and citations by editing this post.
Closed 5 years ago.
Improve this question
I'm working on a project written in Java, designed to transmit data via a messaging system that strictly defines the bit position of the messages fields. This means we have an entire library of dictionary classes designed to bit-shift object input data to/from the message binary representation. This library is reasonably large, and because the protocol is still young, has the tendency to be tweaked and changed every year or so.
The JavaDoc for this library provides ASCII art tables and diagrams that explain what a particular method expects as input (or output). These tables are exceedingly important because finding the documentation and verifying that the method actually does what the document says can be time consuming a prone to error. Following a single, simple ASCII-representation of the bit shifting makes this a lot easier.
I have a coworker who insists that ASCII art does not belong in JavaDoc (even with tags), and furthermore that we configure Eclipse to automatically format the code on save. He offers two options to reformat the documentation:
Embed an image.
Use an HTML table.
The image would be okay, except Eclipse doesn't render SVG images. It is completely unacceptable to me that we maintain an SVG image and then export the image as PNG to our documentation repo, and then link the PNG with HTML. The amount of maintenance involved in that scenario seems completely crazy. Who is responsible for making sure all the PNG, SVG, and code are synchronized?? Furthermore, obviously, the data won't be readable without the image.
The HTML table option is bad for two reasons. First, the Eclipse formatter puts each tag and value on it's own line, which means every single value takes up three lines. It leaves huge gaps in the source code, and is completely unreadable without rendering the HTML. To make matters worse, some of our tables are complex, and troubleshooting HTML tables is not my idea of a responsible thing to require of developers who already resist creating documentation.
So if my coworker is right about "java people" not using ASCII diagrams for documentation, what is a standard, industry practice, that gives us a method for preserving these diagrams? How does this method benefit over using tags with ASCII diagrams? Bonus points if you can answer why JavaDoc hasn't evolved to provide readable markup, instead of relying on HTML.
Edit: I just found markdown-doclet. I don't know if this will be an acceptable compromise or not. Maybe there are other tools that work similarly?
An old question, but I have had similar frustrations.
You can use the /*- construct to prevent Eclipse from formatting a given comment. See: https://stackoverflow.com/a/5466173.
Use the {#code} construct and/or <pre>. See: https://stackoverflow.com/a/542142. I suppose someone who argues against ASCII diagrams in general would argue against these, too. But perhaps it's having been enshrined in Javadoc syntax will be a point in your favor.
Point out that even the Java developers use ASCII diagrams where appropriate.
You could also tell your fellow to use a better editor. No, no, I troll (: ...A little.
At the company we've decided on ASCII diagrams for the primary reasons given already, and we believe they are more than enough to justify this choice:
Maintenance cost and feasibility. I've seen projects with outdated external resources... it's almost inevitable.
Displayed anywhere (IDE, text editor). We don't produce Javadoc for internal projects and put them on a web server. Development habits have changed... see http://www.flowstopper.org/2014/12/graphical-visualizations-in-javadoc.html
ASCII diagrams also force one to keep it simple, which usually helps for clarity.
I've found http://www.asciidraw.com/ to be a great tool for this purpose.
Closed. This question is off-topic. It is not currently accepting answers.
Want to improve this question? Update the question so it's on-topic for Stack Overflow.
Closed 11 years ago.
Improve this question
And by the right guide, I mean one which doesn't necessarily focus entirely on how to program in Java, but puts forth a bit of effort on everything else. In other words, something which has enough information on the things which IDEs like Eclipse do for you, and how to manage those things without using an IDE.
Some examples of what I'm looking for:
How to import Java files without packaging them first.
How to specify directories for file/package imports, and where that specification needs
to be placed.
How to use Gedit to effectively program in Java with nothing but a few plugins and command line for compilation.
Great compiler error avoidance practices.
Seriously, I've looked enough now to come to the conclusion that Google really can't just hack what I need, and my best bet is an actual resource filled with lots of information.
If anyone has any ideas or thoughts on where I should look, or even an answer to any of these questions specifically, I would greatly appreciate the input.
IMHO you can't effectively program in Java without IDE (especially working on bigger project). You should learn about using/setting CLASSPATH, also check documentation for basic JDK commands (javac, java, jar, javadoc etc.).
Eclipse IDE has support for other important project tools e.g. Ant and Maven (for example with M2Eclipse plugin), so you can learn them too if you want.
Check this question for more lightweight IDE than Eclipse.
Java programming is quite a broad area. You may wish to do web-programming or Swing and there are lots of frameworks and framework combinations to work with.
If you want to be productive there is no way you can survive, especially for large projects, without using one IDE, or maybe even two. You will need a simple JUnit integration, as well as a debugger and automatic code generation for POJO methods, and autocompletion and refactoring capability and you name it.
I think that the best IDE for Swing development is Netbeans7. Matisse is implemented best, stable and fast. You can drag and drop anything you like anywhere and the generated code is always clear and well organized.
Eclipse has a great GWT-Designer. It is also great for Struts2 programming etc. Both work great with Maven and Ant and Hibernate.
If you need three months for a project you can do with an IDE in two weeks, there is no point in not using an IDE. On the other hand there are also masochists between us...
I recommend programming with an editor and the shell only for beginners, until they get the grasp of things and understand layouts, jars etc. Using a graphical tool to get started is wrong, since the students learn to drag and drop components mechanically and relying upon lack to get things straight. Only as soon as one knows how things work, is IDE a one way street. You never look back again. There is amazing free software today.
Eclipse has a very thorough Java dev guide, which should tell you pretty much everything it will do for you. http://archive.eclipse.org/eclipse/downloads/drops/R-3.1-200506271435/org.eclipse.jdt.doc.user.3.1.pdf.zip I think the guide does a decent job as far as helping you help yourself as well, so I think it could still be a worthy source for what you are seeeking.
In other words, something which has enough information on the things which IDEs like Eclipse do for you, and how to manage those things without using an IDE.
So you acknowledge IDEs are great. Why aren't you using one? In particular, IDEs come with step by step documentation on how to accomplish these simple tasks. I suspect the reason there is little IDE agnostic documentation on these things is that most people actually use IDEs.
Great compiler error avoidance practices.
I for one wouldn't want to code without the Quick Fix feature of eclipse ...
Closed. This question needs to be more focused. It is not currently accepting answers.
Want to improve this question? Update the question so it focuses on one problem only by editing this post.
Closed 2 years ago.
Improve this question
I have to create an application which automates Outlook and Word and I want to use Java for that task. (The only allowed alternative would be VB6, so...)
After a quick Google survey I found several libraries, but I'm not sure which one to use:
J-Interop
SWT
JACOB
COM4J
jacoZoom
...
I have no idea how to compare these libraries and make an informed decision. It seems that COM4J is a little bit outdated, JACOB leaks memory (allegedly) and jacoZoom is commercial. Each and every one seems to require a lot of boilerplate code to perform a simple method call. (Which might be unavoidable given the design of COM)
Besides that I have no idea how to choose between one of them. Which one is the best?
We use Jacob in production environment and it works out pretty well. Nevertheless the projects seems to be not very active.
Speaking of which: Activity seems to be an advantage for J-Interop. We tried the project as well and it seems to work out pretty good with even better logging messages. I think we might choose J-Interop for new projects.
COM4J seems to be outdated, you're right.
As a developer seasoned in Java/Linux but ignorant in Windows, here was my experience (August 2015)...
Executive summary:
Go with com4j... with the caveat that:
You may need to build the latest (unreleased) code to get some important recent fixes.
Longer story:
At first, the propensity for code involving JNI to crash inexplicably made me look for a non-JNI solution. J-Interop seemed to fit the bill.
However, as I tried to get j-interop to work, all the Windows DCOM permissions and registry crap made it a total PITA. It's different for different versions of Windows, required changes must be made as Administrator, etc. I don't understand any of this Windows crap and it makes me want to puke anyway.
I then tried com4j and it worked like a champ. This project is very nicely designed. It auto-generates Java interfaces from the DLL's you are using. COM calling convention details are declared using Java annotations on the interface methods, allowing you to tweak these if necessary (no tweaks were necessary in my case).
There are several developers on github who have forked the project and contributed back fixes, which is a healthy sign.
The only caveat is that you may require some of the recent fixes which, as of August 2015, are merged into the project but not contained in the latest release (which is from March 2014).
So you may need to do a custom build yourself, which includes building DLL's in Visual Studio, etc. Even as a Windows hater/ignorant, I was able to do this.
COM4J still seems to be active - it has been moved to Github and has a new homepage:
http://com4j.kohsuke.org/tutorial.html
J-Integra by Intrinsyc Software http://j-integra.intrinsyc.com/ is your best option. It hides the complexity of having to know an unfamiliar programming language. It isn't dependent on JNI so you don't need to know JNI. J-Integra is also actively maintained and supported and Intrinsyc offers a pure 64-bit version for those people wanting to run in a pure 64-bit environment.
Intrinsyc offers free trials so you can test it out and see if it works before committing to any purchasing.
Companies like HP, IBM, SAP, and Oracle use it so you know its going to be fast, stable and well supported.
Appears bridj can do some COM interop as well: https://code.google.com/p/bridj/wiki/COM#Example
Closed. This question needs to be more focused. It is not currently accepting answers.
Want to improve this question? Update the question so it focuses on one problem only by editing this post.
Closed 8 years ago.
Improve this question
We're trying to determine how to implement a simple plugin framework for a service we are implementing that allows different types of calculators to be "plugged-in".
After reading a number of posts about Java plugin frameworks, it seems like the most common options are:
OSGI
"Rolling your own" plugin framework
The Java Plugin Framework (JPF)
The Java Simple Plugin Framework (JSPF)
OSGI seems to be more than we need.
"Rolling your own" is ok but it would be nice to reuse a common library.
So we're down to the JPF and JSPF. JPF doesn't seem to be in active development anymore.
JSPF seems very simple and really all we need. However I haven't heard much about it. I've only seen one post on StackOverflow about it. Does anyone else have any experience with JSPF? Or any other comments on this design choice?
Update: There isn't necessarily a correct answer to this.. however we're going to go with Pavol's idea as we need just a really, really simple solution. Thanks EoH for the nice guide.
(Disclaimer: I am the author of JSPF, so better take my comment with a grain of salt ;-)
The main reason I started with the JSPF was because I had the same problem as you have now: I was looking for a simple solution to make my thesis-project 1) extensible and 2) give it a more or less clear code structure.
The reason why I haven't decided to use an existing framework was because most of them were so heavyweight to start with, that I got lost in reading documentation and was almost forgetting my original task. So, according to your statement
We're trying to determine how to
implement a simple plugin framework
for a service we are implementing that
allows different types of calculators
to be "plugged-in".
I'd think that you could give JSPF a shot and see how far you come within one or two hours.
However, the final decision also depends a bit on what exactly you want to achieve, and the specific circumstances.
I have heard positive results from a number of individuals who have been using it to structure their projects or load plugins in their projects. On the other hand, I also know of one person in our department who discarded it again because he didn't feel it was mixing well with his programming style.
So, to answer your question briefly (and surely in a biased way), I would use
OSGi for projects and teams
which are large and have many people working on it
that justify the overhead of setting up the infrastructure
in need of the specific services offered
JPF for projects and teams
of medium size (?, honestly I am not sure about the project / team size they are targeting)
which are in need of more structured facilities to organize their code, like XML configurations, detailed plugin lifecycle management, extensible plugins ...
JSPF for projects and teams
of small size, following an agile paradigm
that just need something that works out of the box, without the need of configurations or setup
willing to sacrifice some features for simplicity
I hope you find the plugin framework most suitable for your scenario. And, no matter what you try, I would be happy to hear about your results.
If you are planning to have just one (or only a few) not very complex 'extension points' than perhaps a well-defined SPI and a piece of configuration might be sufficient. No need to use a plugin framework.
By piece of configuration I mean some mechanism to find your plugins. For example something like META-INF/services/ or simply listing your plugins in a configuration file.
More details (upon request):
SPI = Service Provider Interface, an "implementer-side equivalent of an API". To learn more try searching for a difference between API and SPI. However in this context it is just a fancy term for an interface to be implemented by your plugins (i.e. defines the contract for your plugins).
A nice, short article "Creating a Service Provider Interface" by Ethan Nicholas describes how to create your own SPI in similar way as it is done in several part of the Java Platform itself.
META-INF/services/ can be seen as a more generalized approach to creating SPIs. More information can be found in the respective section of the JAR File Specification.
If you need a really simple solution, try jin-plugin. It is a minimalistic plugin framework for Java and PHP.
Closed. This question is off-topic. It is not currently accepting answers.
Want to improve this question? Update the question so it's on-topic for Stack Overflow.
Closed 10 years ago.
Improve this question
I'm working on getting an Introduction to Groovy presentation ready for my local Java User's Group and I've pretty much got it together. What I'd like to see is what you all think I just have to cover.
Remember, this is an introductory presentation. Most of the people are experienced Java developers, but I'm pretty sure they have little to no Groovy knowledge. I won't poison the well by mentioning what I've already got down to cover as I want to see what the community has to offer.
What are the best things I can cover (in a 1 hour time frame) that will help me effectively communicate to these Java developers how useful Groovy could be to them?
p.s. I'll share my presentation here later for anyone interested.
as promised now that my presentation has been presented here it is
I don't know anything about groovy so in a sense I've qualified to answer this...
I would want you to:
Tell me why I would want to use Scripting (in general) as opposed to Java-- what does it let me do quicker (as in development time), what does it make more readable. Give tantalising examples of ways I can use chunks of scripting in my mostly Java app. You want to make this relevant to Java devs moreso than tech-junkies.
With that out of the way, why Groovy? Why not Ruby, Python or whatever (which are all runnable on the JVM).
Don't show me syntax that Java can already do (if statements, loops etc) or if you do make it quick. It's as boring as hell to watch someone walk through language syntax 101 for 20min.
For syntax that has a comparible feature in Java maybe show them side by side quickly.
For syntax that is not in Java (closures etc) you can talk to them in a bit more detail.
Remember those examples from the first point. Show me one, fully working (or at least looking like it is).
At the end have question time. That is crazy important, and with that comes a burden on you to be a psuedo-guru :P.
I'm not sure about how the Java6 scripting support works but I'm fairly sure it can be made secure. I remember something about defining the API the script can use before it's run.
If this is the case then an example you could show would be some thick-client application (e.g. a music player) where users can write their own scripts with an API you provide them in Groovy which allows them to script their app in interesting and secure ways (e.g. creating custom columns in the playlist)
I'd go for:
Closures
Duck typing
Builders (XML builder and slurper)
GStrings
Grails
I'd mention the following things in addition to what has already been stated:
GDK - extensions/additions to existing JDK classes
Interaction between Groovy and Java code (basically a non-issue)
Compiling Groovy code to Java .class files
XML parsing and mechanisms for accessing document content
One thing I like doing with Groovy is implementing an interface defined in Java as a map from method names to closures. It's a cool thing you can do with Groovy, but probably well beyond an introductory presentation though.
Include an example of how making Java code more groovy takes away soooo much code. Wait for them to pick their jaws up off of the floor before continuing. Scott Davis has a simple example at the beginning of Groovy Recipes that takes 35 lines of Java or 3 lines of Groovy.
You should definitely show them how to create a quick Grails application. Two domain classes that are related. Build a basic CRUD app. Explain that tables are being created behind the scenes using GORM(Hibernate). Then explain that you can create a war file and deploy it as you would any other Java war file. You can also add Grails/Groovy to an existing Java/JSP project so it doesn't require a huge commitment or paradigm change.
Groovy/Grails is simply Ruby/Rails for Java people. I'd cover the plugins for Netbeans/Eclipse too. Groovy/Grails are just now getting full support in the major IDE's.
Finally, if you can find a good diagram that shows how Grails is built on top of Spring, Hibernate, Quartz, Sitemesh and Groovy, I think people will understand that there is a treasure chest waiting to be unlocked.