Please update the 3.0 Template and Examples for JBoss 3.2

[gil]

Problem:

When using JBoss 3.0 Template And Examples on JBoss 3.2, the sample app "template" fails to deploy, with various cryptic errors.

This is a major pain for new JBoss users. Most newbies work through the QuickStart document
to learn the ropes. Since QuickStart-30x is the only startup document in town, many, like me, have run straight into this quagmire, and wasted hours/days troubleshooting the sample files (see details below).

This creates a bad impression of JBoss, and inspires no confidence in new users. But it could be solved by releasing an updated template/examples package that works with JBoss 3.2.

In the short term, a warning message should be added to the QuickStart document - "the 3.0 example code will not work with JBoss 3.2 and above".

Here are some more details about the problem, and how to fix it.

Typical deployment error messages:

"Error in ejb-jar.xml for Entity Bean test/TestEntity: The ejb-name for a CMP2.x Entity must be a valid Java Identifier"

"Warning: Every finder method except findByPrimaryKey(key) must be associated with a query element in the deployment descriptor."

Fix:
1. edit TestEntityBean.java, modifying @ejb:bean and @ejb:ejb-ref tags

remove the illegal "test/" prefix, eg.
@ejb:bean name="test/TestEntity" becomes
@ejb:bean name="TestEntity"

[note 1: leave the jndi-name attributes alone]
[note 2: repeat this step for all the example beans (entity/*.java, message/*.java & session/*.java)]

2. modify the TestEntityBean.java finder tags

delete the @ejb:finder and @jboss:finder-query tags, and replace with the following:

* @ejb:finder signature="java.util.Collection findAll()"
*
* @ejb:finder signature="test.interfaces.TestEntity findByName( java.lang.String pSurname, java.lang.String pLastName )"
* query="SELECT OBJECT(t) FROM TestEntity t WHERE t.firstName = ?1 AND t.lastName = ?2"
*
* @ejb:finder signature="test.interfaces.TestEntity findAnotherByName( int pId, java.lang.String pSurname, java.lang.String pLastName )"
* query="SELECT OBJECT(t) FROM TestEntity t WHERE t.id <> ?1 AND t.firstName = ?2 AND t.lastName = ?3"
*

3. modify the TestEntityBean.java @ejb:ejb-ref tag (the 2nd line is missing, causing run-client to fail)

* @ejb:ejb-ref ejb-name="SequenceGenerator"
* ref-name="ejb/test/SequenceGenerator"

4. rebuild

Other Forum Ref: http://www.jboss.org/modules/bb/index.html?module=bb&op=viewtopic&t=

[vvp]

> This is a major pain for new JBoss users.

> This creates a bad impression of JBoss, and inspires
> no confidence in new users.

Truer words have never been spoken!

[corecaptain]

I second that.

I just discovered the serious lack of docs happenstance as I was attempting to download the templates. I was unable to download the templates as the link referencing them on www.jboss.org is broken.

If I hadn't read some many positive things about jboss, the minute I discovered this lack of docs I would
have just deleted jboss and stopped wasting my time.

I will continue to work to work to get Jboss up and running and am hoping this forum and other harder to find sources on the web will get me started.

HOWEVER...

Mindshare is a terrible thing to waste.

jboss.org likes to cite the number of downloads
but how many of these people are just hitting
the wall on the lack of docs and quitting.

I understand that jboss Inc. wants to make some $$ on the documentation. I would have no trouble paying the prices for the docs. BUT first I need to
get started.....there is nothing like a free sample to get the pump primed....think about it!

[ahmedferdous]

I bought the documentation called JBoss Admin and Devel guide today..expecting I will find some step by step process..how to develop and deploy EJB s in JBoss 3.2.1..I think I have wasted my 10 dollars. The name of thebook was confusing.

[premierobjects]

Gil,

Your thoughts are correct. I have been using JRun for sometime now, thought I would see if I could get our app running on Jboss. As a newbie to jboss, I have experienced documentation that does not reflect the binary release. After purchasing the docs and attempting to work/debug my way through the startup docs, 2 days have gone by and I still can't create/deploy my own session bean. A very frustrating experience.

Makes me appreciate app server I am currently using.

[danl_thompson]

Gil, where did you even find the template project? I found a very old one witha google search. But none that actually work.

By I wish I could help these guys with this documentation / template issue, it's driving everyone nuts.

dt

[gil]

hi dt,

There *was* a link halfway down the downloads page, but it has been quietly removed.

Maybe that means they are about to update/replace it? Here's hoping...

Gil

[rharwood]

Hear, hear!
The QuickStart-30x.pdf I just downloaded doesn't even correspond to the JBoss.3.0TemplateAndExamples.zip I downloaded. The zip file appears to be an older project.
Say what? Why aren't they bundled as one coherent entity?

[t4b00m]

Not to continue this list but I have to also agree fully. The quick start should be considered a core part of each release. I was looking at Jonas and JBoss and almost completely dropped JBoss because of the poor initial start. Lukily this post was up and easily available.

[paulmoore100]

the fundamental problem is that the devs are writing the docs - this are two different skills. Also the devs know so much they forget that others dont.
Nobody would suggest that technical writers write the code but somehow the opposite way round never seems to raise any concerns. Problem is that tech writers dont work for free.
My experience is that without the source code this product would be unusable - now the good thing is that I have the source code, the bad thing is that this means its not ready for prime time in the sense that you have to read the code to work out how to make it do things.

I would happily spend $$ on good docs. Plus there MUST be samples