8 Replies Latest reply on Apr 6, 2010 12:46 PM by Peter Johnson

    Desperate for some documentation...please?

    Ken Kopelson Novice

      I am new to JBoss and am having trouble getting a simple Web Service working under Eclipse.  The main problem I am having is getting solid documentaiton that is complete and accurate.  I have two eBooks, one JBoss in Action, and JBoss AS 5 Development, but neither provides up-to-date information or examples that work.  I installed JBoss AS 5.1 and then followed the instructions provided in all the various examples I could find, and I keep getitng errors like "Invalid Port Type" or such things as that.  All the examples have values in their various annotations or XML config files that are not clearly documented, and the documentation that I can find it either out-of-date, sparse with no explanations, or incomplete.


      Even the example provided in the JBoss documenation is incomplete since it only shows Java code for the class of a EJB and not the interface.  The interface is important to show since it requires some annotations also (apparently) because it is the interface name that is referenced in the WSDL, not the class... at least that is how it appears.


      What I really need is:


      1) A good example of a simple EJB Web Service, including the class, the interface, the web.xml, and any and all other configuration informations.  It should be clear about how things should be named, such as the end points, the SOAP type, the WebService annotation options like "name", "ServiceName" etc.  This is really where the problem is because I found that somebody else was having the same trouble as me (on google) and they said in their forum post "I changed the names to such-and-such and it fixed the problem" but then no explanation as to why it then worked.  A single, tested, complete example of a working WebService (hello world) that documents any assumptions about the environment (such as endpoint URL) and also provides a little discussion about options that can be chosen, would be very useful and helpful.


      2) Some up-to-date documenation that gives tangible and complete examples of how things should be done with the new AS 6.  It seems that most documentation assumes that people already know JBoss, or have been using it for years, or are already familiar with all the new terms, etc.  It seems that the books out there are either out-of-date or not very complete.


      Please help... I need this for my job as soon as possible... many thanks in advance!


        • 1. Re: Desperate for some documentation...please?
          Peter Johnson Master

          For JBoss in Action we (the authors) completely avoided Eclipse which is a good thing because how things are done in Eclipse has changed fairly drastically since we started working on the book. If you stick to using Eclipse as a text editor you should be fine. Also, you really need the JBoss Tools plugin to do web services for JBoss AS; if you don't have it then Eclipse uses Axis for web services, which will not work.


          A previous poster pointed out the the EJB web service in JBoss in Action does not have an interface. You can see the discussion here:

          hmm, can't find the discussion, i'll have to do some more digging and post the link later


          >>I keep getitng errors like "Invalid Port Type"

          Providing a complete stack trace would help. Port problems are unfortunately all too typical because of interactions with other applications. Also, if the issue is really with the "web service port", then the full source and configs for the app would help. Have you run the ant build for the examples in chapter 9? Did those work for you. I have verified that they run on JBoss AS 5.1.0. (By the way, make sure you get the JBoss in Action source code from the Subversion repository, it contains many fixes related to 5.1.0 that are not in either of the two ZIP files, see the wiki on the source code web site for more info)


          >>All the examples have values in their various annotations or XML config  files that are not clearly documented,

          Please indicate which values in JBoss in Action are not clearly documented, I'll be glad to supply the explanation.

          • 2. Re: Desperate for some documentation...please?
            Peter Johnson Master

            Here is the discussion I was thinking about:



            It is actually about WS-Security, but the example the OP shows uses an interface for the EJB.

            • 3. Re: Desperate for some documentation...please?
              Ken Kopelson Novice

              Thank you Peter for the information.  I have been thinking that perhaps it would be better for me to use JBoss 6 since it provides a better method validating SOAP messages amongst other things.  In general, do you think AS 6 would be a better platform for developing Web Services?  If I do go with 6.0 will the same examples you provided work?  I am back to work tomorrow so I will try using the example you provided to develop a base Web Service that I can successfully call from a Java client program (as shown in the example).  If I have any more troubles, I would very much appreciate your continued help until I can just get a working service... from there I can add all the functionality needed quite easily.  Once again, thanks for the help.  I really appreciate it.

              • 4. Re: Desperate for some documentation...please?
                Peter Johnson Master

                I am sorry but I have not had the time to do much work with AS 6, so I could not say. I have not even attempted to convert the JBoss in Action examples to AS 6. Also, be aware that AS 6 is in beta so things can change dramatically between now and when it finally goes GA (ask anyone who followed the betas and release candidates for AS 5...)

                • 5. Re: Desperate for some documentation...please?
                  Ken Kopelson Novice

                  Thank you Peter... regarding AS 6 Beta, I do believe they are now using a completely different method of doing things... no longer Beta testing, but instead using the Milestone method where they add features in a complete and tested way a few at a time until all features are added for the AS 6 release.  I do believe that this means we can now count on the features that get added with each Milestone to be essentially complete and final.  I watched a video of the lead developer for JBoss explain this, stating that they went to this new model precisely for the reason you state... they want people to be able to use the features as they come out, and not to have to wait until the features become "finalized" so to speak.


                  If anyone has any different understanding, please let me know.



                  • 6. Re: Desperate for some documentation...please?
                    Peter Johnson Master

                    That might work for new things, but the JBoss engineers are constantly replacing existing components with new components, and when they do old stuff stops working. Example: 6m2 changed the way logging is defined. Thus anyone who set up logging in 6m1 has to redo it based on the changes. A similar thing will happen when they switch from JBoss Messaging to HornetMQ (I think that is planned for M3). Sure, if you use only the Java EE APIs, you are probably in good shape. But for any configuration information, you will scramble to make updates. And web services can use a lot of configuration information. (Though I have to admit that web services configuration was fairly constant through the various AS 5 betas...)

                    • 7. Re: Desperate for some documentation...please?
                      Ken Kopelson Novice

                      Hi Peter,


                      Well today I was able to make a very simple Web Service work, at least for a while, but then it broke again.  Basically, what I am after is as follows, since I do not yet believe that I have seen what I am really looking for, partly because I didn't even know how to ask the question properly until just today after spending more time wrestling with this thing.


                      What I really need is a comprehensive example of how to write a Web Service that accepts a SOAP message using Document/Literal, unwraps the XML payload and sends back a response.  A discussion of the tradeoffs between using WRAPPED and BARE parameters would also be helpful.  There are apparently several ways to pass the message to a service method, but to keep it portable I found a document that says it is recommended (I don't know by who) to use SOAPElement type, but then it says to use WSDL-to-Java method, which doesn't seem to work from Eclipse (top-down method), and it seems quite a bit messier from a code point of view, etc.  The problem with all the tutorials and the books I've seen is that none of them provide a comprehensive reference of ALL possible configuration values, along with explanation of when a certain setting should be used.  Apparently, you can send a SOAP message to the service as a Source, a String, or a SOAPElement, but the WSDL doesn't accept the SOAPElement type, and must have the type set to "anyType", but that gets converted to a Java "Object" type by the "consume.bat" utility and I don't know how to map the "anyType" to a SOAPElement type.


                      Perhaps I need a good book just on Web Services for JBoss.... is there such a thing?


                      Every single tutorial I have seen so far seems either too simplistic or it leaves something out, whether it is a configuration setting, a configuration file, an Annotation, or something else, and these bits that get left out are not easily known since the documentation online is always out-of-date.  Also, when a configuration setting is shown, it is often not documented as to why that setting is used, or the other alternatives are not documented so that an informed decision can be made.


                      Generally, this seems way too difficult for what it actually does.  Maybe it's not dificult for someone who already knows by memory all the config options, and how to use them all, but since many people (including me) are not in that boat, I think things could be a lot easier if only there was update-to-date, comprehensive examples for ALL the various ways that JBoss can be used, especially the most common ways like Web Services.


                      A comprehensive example of a full blown Web Service (all files needed) that accepts a SOAP Document from any kind of system, breaks it apart, does something with the data, and then constructs a return message, would be quite helpful.


                      Thank for very much for your help!

                      • 8. Re: Desperate for some documentation...please?
                        Peter Johnson Master

                        Now I see what you are asking for. You want a book on web services, one that goes beyond the basics and gets into the nitty-gritty details. JBoss in Action is centered around configuring the app server, so we spend more time on working with config files than on anything else. The only reason the chapters contain simple apps is that we needed demo apps to explain the various configuration options. Unfortunately, I am unaware of a book on Java web services that goes into the detail that you are asking for.


                        But the offer to explain any source code or config settings in JBoss in Action that are not sufficiently explained is still open.