cxf-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Christian Schneider <ch...@die-schneider.net>
Subject Re: Concerns about the Camel / CXF documentation
Date Thu, 28 Aug 2008 10:15:39 GMT
Glen Mazza schrieb:
> Christian,
>
> I have a few concerns about your write up on using Camel as a JMS
> alternative with CXF[1]:
>
> 1.)  I don't understand why you are duplicating your blog entry on a CXF
> confluence page.  Can't you just keep your blog entry up-to-date with your
> link to it from our articles[2] page (and perhaps a few sentences on our JMS
> page linking to it, for those who miss the articles page)?  Your article
> looks nicer on your blog anyway than it does with Confluence formatting.
>   
Hi Glen,

I also use confluence on my blog. So the duplication effort is at least 
quite small. The reason why I duplicated the content is that I on the 
one hand wanted
to really contribute the article to cxf so anyone on the wiki can 
improve it later. On the other hand I wanted to establish my blog. If I 
only wrote the article on my
blog no one would be able to do modifications beside myself. If I only 
had written the article on the Wiki I could not establish my blog. Shame 
on me for using CXF for this ;-) I can cut the link if you think it is 
inadequate.

Btw. if the article looks nicer on my blog we could perhaps improve the 
design of the cxf confluence pages ;-)
> 2.)  The quality of the writing on the Confluence page is not very clean--it
> hasn't been spell-checked, capitalization is frequently off ("apache camel"
> instead of "Apache Camel"), detracting from the CXF documentation as a
> whole, and the tone reads too informally.  Also, you have too many
> references to specific developers and regular usage of the first-person
> "I"--it is written like a blog entry instead of actual system documentation. 
> We really don't have time to be cleaning this documentation up, you need to
> proofread more carefully.
>   
That´s why I started the article on my blog and announced it on the 
mailing list. I hoped that some of these problems would be found before 
I added the article to the wiki.
But I got no response on the list so I added the article a day later. I 
will try to improve the style and naming schemes today if that is ok.
> I write blog entries and link them to the articles page, and I also update
> the CXF system documentation (sometimes linking to a blog entry, either mine
> or others).  But the writing styles are different, and the types of things
> you include are different.  In particular, you are tying your Confluence
> article too much to yourself, but Confluence pages are for any team member
> to edit, and are normally written without reference to any particular
> author.
>   
Thanks for the hints about the style. I will try to do this better in 
the future. Perhaps it is a good idea to
write a howto on the project page in a neutral style. Then I could pack 
an announcement to the howto together with my personal opinions on my 
blog in a personal style. So the two
would be separated nicely. I think I still have to learn a bit aboutt 
blogging ;-)
> 3.)  The tone of the documentation would appear to make it a better
> candidate on the Camel site rather than the CXF one, for two reasons.  (And
> I'm sure James Strachan would be happy to give you a place to write
> articles.)  For one thing, the criticisms of the CXF product, as in your
> entry paragraphs, is unnatural within CXF documentation.
>   
You are right. I think it would be better to add the Howto to the Camel 
site and link it from CXF Howtos. I can move the article.
The problem with the current Camel site is that you almost do not find 
the Camel CXF Transport although it is
the better solution than the CXF component. For me the main idea behind 
publishing this article was that I had many problems configuring
JMS for CXF and that the Camel integration really helped. So I hope to 
help others with configuring JMS. If I would only add the article to the 
Camel Wiki
the CXF users who do not need Camel but have problems with JMS would not 
find it.

As a second intention I would like to help improve the CXF JMS config 
and hope that the style Camel uses can be a good pattern for an improved 
native JMS
config for CXF.
> Quote:  "Configuring JMS in Apache CXF is possible but not really easy or
> nice. This article shows how to use Apache Camel to provide a better JMS
> Transport for CXF...JMS configuration in Apache CXF is possible but the
> configuration is not very flexible and quite error prone. In CXF you have to
> configure a JMSConduit or a JMSDestination for each webservice. The
> connection between Conduit and the Service proxy is the endpoint name which
> looks like "{http://service.test\}HelloWorldPort.jms-conduit". As this name
> is never explicitly configured elsewhere it is quite probable that you
> misspell the name. If this happens then the JMS Transport just does not
> work. There is no good error reporting to show you what you did wrong."
>
> Pointing out the minuses of a software product, such as CXF, is perfectly
> acceptable, but not on the CXF's product's page itself--this should with the
> Camel project, where you are explaining an alternative.  That's where you
> establish the contrast, the criticisms that you're finding with CXF.  While
> you can still link to alternative and better solutions from the CXF site
> (and even say they're better), the self-criticism part directly within the
> system documentation seems strange.
>   
As mentioned above I hope to help people with JMS problems in the short 
run and help improve CXF JMS
in the long run. Sorry if this criticism is too harsh. Perhaps it suites 
better when I place the article on the Camel wiki.
I can also try to be a little less harsh in the criticism. The only 
reason why I wrote this passage anyway was to motivate
why you should use a separate product to configure CXF JMS. My intention 
is in no way to move people to Camel or something.
I only hope to help the users of CXF and improve CXF.

> For example, if I want to suggest where Maven is better than Apache Ant for
> building software, those technical articles (and legitimate criticisms) go
> on the Maven website ("Apache Ant is good for many things, but falls short
> in these project-building aspects...), not on the Ant website.  It is
> unusual to ask team members to maintain documentation criticizing their
> project.  
> For the second reason, Camel embeds CXF--not vice-versa; for that reason,
> perhaps placement on the Camel site would appear more appropriate, with just
> links from CXF.
>
>   
I understand. So moving the article to Camel is a good idea. Is it ok to 
link to the Camel article from the Wiki though?

Btw. What do you think about improving the JMS config for CXF? Would you 
think the style from Camel I showed is good? I really like
the idea to choose the JMS connection in the address rather than in a 
separate conduit definition. I also think it´s great to use Spring 
internally to
make use of their transaction management. The last thing I liked is 
refrencing the ConnectionFactory as a bean.

Best regards

Christian

-- 

Christian Schneider
---
http://www.liquid-reality.de


Mime
View raw message