You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@river.apache.org by Patricia Shanahan <pa...@acm.org> on 2015/01/06 00:07:11 UTC
Getting Started
I have completed buying a new home, moving into it, and selling the old
one, followed by Christmas in England and recovery from the cold I
caught there. That means I'm ready to get much more active in River.
Last year, we got some feedback suggesting that better support for new
users might remove a barrier to community building. My main agenda is
community building, so I want to work on that. I am going to be a very
naive potential user, so stand by for basic questions.
I began by downloading the binary version, since in this mode I am not
interested in being a River developer. However, when I looked at the
"Getting Started" page,
river.apache.org/user-guide-basic-river-services.html, it says:
"The instructions assume that you're building from source as checked out
from the SVN trunk. Currently this is necessary because the code
snippets below use methods and classes which, at time of writing,
haven't made it into the latest binary release yet. Having said that,
the code you will need in the binary release isn't to far removed from
what you'll see below, so you can progress with the binary release if
you want to and are happy odifying the code."
According to the page info, the "time of writing" was no later than
November 23, 2013. Do I still need to do a River build before I can run
the example? If so, why and what can I do to fix that?
I have no idea whether or not I would be happy "odifying" code - maybe
"modifying"?
What is the best procedure for editing the "Getting Started" page? I
want to make sure that any changes I make really are improvements, so I
would like PMC review as I go along.
Patricia
Re: Getting Started
Posted by Greg Trasuk <tr...@stratuscom.com>.
Hi Patricia:
Maven is pretty mainstream at this point in time (very much in open source, it’s also beginning to hit the later adopters in the corporate world).
Having said that, the Maven site makes it look much harder than it is. Let me boil it down a little.
1 - From the command line...
============================
- Download the latest Maven from http://maven.apache.org/download.cgi
- You probably want the binary zip
- Unpack that file somewhere convenient
- The unpacked file contains a ‘bin’ folder. Put that ‘bin’ folder in your command path
- At the command line, type ‘mvn -version’. Does that run? If yes, you’ve installed Maven.
- Now you can go to the project directory, e.g. river-examples, and type ‘mvn install’.
2 - From Netbeans
===============
- Netbeans includes Maven 3.0.5, which I don’t think has the markdown processor for the documents that I created. So it’s better to use a local Maven installation, so…
- Download the latest Maven from http://maven.apache.org/download.cgi
- You probably want the binary zip
- Unpack that file somewhere convenient. This is your “Maven Installation” dir.
- In Netbeans, select Preferences - > Java -> Maven and point it to the unpacked Maven dir.
3 - What Maven Does…
===================
Maven processes a set of source files and/or submodules to produce an ‘artifact’. Typically an artifact is a jar file, but it could also be an unpacked directory.
We talk about a ‘Maven Module’. This is a folder that contains a file called ‘pom.xml’ and all the source code and/or submodules. Source code is under ‘src’. Anything produced by Maven is under ‘target’. ‘pom.xml’ is essentially a description of the artifact. In particular, it includes a list of artifacts that this artifact depends on. One module should produce one artifact. When we have more than one artifact, or an artifact that depends on other artifacts, we use a “Multi-module” project. This is simply a module who’s ‘pom.xml’ specifies submodules.
Maven processes your source file, based on the requirements in ‘pom.xml’ to produce an artifact. Typically this artifact gets installed in a local repository, that usually resides in ~/.m2/repository. Typing ‘mvn install’ in the module folder tells Maven to do this installation. Maven is bright enough to know that it has to compile and package the artifact first.
While doing the build, if Maven finds a dependency that it doesn’t already have a copy of, it goes off to a central repository called ‘Maven Central’ and downloads it to your local repository. All of River’s compiled jars are available through Maven Central.
Hopefully that makes my previous explanation make a little more sense. If not, just shout…
Cheers,
Greg Trasuk.
On Jan 8, 2015, at 1:37 PM, Patricia Shanahan <pa...@acm.org> wrote:
> For me, the next step in this flow is to learn Maven.
>
> In general, is it reasonable to assume that, if I had been working actively as a programmer for the last few years, I would have already learned Maven?
>
> If not, we need to document, at least by reference, the steps involved to get far enough along with Maven to try out River.
>
> Patricia
>
> On 1/5/2015 7:16 PM, Greg Trasuk wrote:
>>
>> I started working on making new demos and “getting started” stuff
>> back before the holidays. Here’s my thinking…
>>
>> As Patricia alludes to, it really shouldn’t be necessary to build the
>> River distribution in order to try out some samples and get started.
>> After all, the artifacts are published on Maven Central, so they can
>> simply be referenced in a Maven build (or Gradle, Ivy, Etc).
>>
>> Towards that end, I started building a new Mavenized ‘examples’
>> project, which can be checked-out from
>> https://svn.apache.org/repos/asf/river/river-examples/river-examples/trunk.
>>
>> In that project, there are currently modules for the service browser
>> jars and a ‘home’ folder for the compiled and packaged examples.
>> (might be best to download it and do a ‘mvn install site’). There’s
>> also documentation for the examples under the main project (look at
>> <project-home>/target/site/index.html - this should be familiar to
>> Maven users). The documentation currently includes how to build and
>> run the service browser (although I think right now it’s incomplete
>> on how the configuration works - haven’t looked at it since Dec 15).
>>
>> Right now, the project has a dependency on the new ‘river-rt-tools’
>> modules that I talked about back in December as well. So in order to
>> run the examples, you currently need to checkout
>> 'https://svn.apache.org/repos/asf/river/river-rt-tools/trunk' and do
>> a ‘mvn install’ on it, which will install the runtime tool artifacts
>> (start.jar) in your local Maven cache. In the end, those artifacts
>> would also be released and published on Maven Central, so you
>> eventually wouldn’t need to build the runtime tools separately.
>>
>> My plan is to add modules to the river-examples project for a
>> 'hello-service’ and ‘hello-client’, as well as a config for the
>> infrastructure services (Reggie, etc). So eventually, the “getting
>> started” instructions become “have a look at ‘river-examples’”, and
>> we’d remove the (very confusing, if you ask me) ‘examples’ folder
>> from the JTSK distribution. As a bonus, we can isolate new users
>> from the convoluted build system in River.
>>
>> If this seems like a reasonable path forward for our “getting
>> started” experience, perhaps you’d like to work on bringing over some
>> of the examples from the JTSK to the ‘river-examples’ project. That’s
>> probably also a good way to re-familiarize yourself with Jini. I
>> probably won’t have any cycles to work on it seriously for the next
>> couple weeks, but could cheerfully make suggestions.
>>
>> You should be able to check-out these two Maven project in the IDE of
>> your choice. I was using NetBeans, but AFAIK, Eclipse should be able
>> to use the Maven build directly. I just haven’t tried it.
>>
>> Cheers,
>>
>> Greg Trasuk.
>>
>> On Jan 5, 2015, at 6:07 PM, Patricia Shanahan <pa...@acm.org> wrote:
>>
>>> I have completed buying a new home, moving into it, and selling the
>>> old one, followed by Christmas in England and recovery from the
>>> cold I caught there. That means I'm ready to get much more active
>>> in River.
>>>
>>> Last year, we got some feedback suggesting that better support for
>>> new users might remove a barrier to community building. My main
>>> agenda is community building, so I want to work on that. I am going
>>> to be a very naive potential user, so stand by for basic
>>> questions.
>>>
>>> I began by downloading the binary version, since in this mode I am
>>> not interested in being a River developer. However, when I looked
>>> at the "Getting Started" page,
>>> river.apache.org/user-guide-basic-river-services.html, it says:
>>>
>>> "The instructions assume that you're building from source as
>>> checked out from the SVN trunk. Currently this is necessary because
>>> the code snippets below use methods and classes which, at time of
>>> writing, haven't made it into the latest binary release yet. Having
>>> said that, the code you will need in the binary release isn't to
>>> far removed from what you'll see below, so you can progress with
>>> the binary release if you want to and are happy odifying the
>>> code."
>>>
>>> According to the page info, the "time of writing" was no later than
>>> November 23, 2013. Do I still need to do a River build before I can
>>> run the example? If so, why and what can I do to fix that?
>>>
>>> I have no idea whether or not I would be happy "odifying" code -
>>> maybe "modifying"?
>>>
>>> What is the best procedure for editing the "Getting Started" page?
>>> I want to make sure that any changes I make really are
>>> improvements, so I would like PMC review as I go along.
>>>
>>> Patricia
>>>
>>>
>>
Re: Getting Started
Posted by Patricia Shanahan <pa...@acm.org>.
For me, the next step in this flow is to learn Maven.
In general, is it reasonable to assume that, if I had been working
actively as a programmer for the last few years, I would have already
learned Maven?
If not, we need to document, at least by reference, the steps involved
to get far enough along with Maven to try out River.
Patricia
On 1/5/2015 7:16 PM, Greg Trasuk wrote:
>
> I started working on making new demos and “getting started” stuff
> back before the holidays. Here’s my thinking…
>
> As Patricia alludes to, it really shouldn’t be necessary to build the
> River distribution in order to try out some samples and get started.
> After all, the artifacts are published on Maven Central, so they can
> simply be referenced in a Maven build (or Gradle, Ivy, Etc).
>
> Towards that end, I started building a new Mavenized ‘examples’
> project, which can be checked-out from
> https://svn.apache.org/repos/asf/river/river-examples/river-examples/trunk.
>
> In that project, there are currently modules for the service browser
> jars and a ‘home’ folder for the compiled and packaged examples.
> (might be best to download it and do a ‘mvn install site’). There’s
> also documentation for the examples under the main project (look at
> <project-home>/target/site/index.html - this should be familiar to
> Maven users). The documentation currently includes how to build and
> run the service browser (although I think right now it’s incomplete
> on how the configuration works - haven’t looked at it since Dec 15).
>
> Right now, the project has a dependency on the new ‘river-rt-tools’
> modules that I talked about back in December as well. So in order to
> run the examples, you currently need to checkout
> 'https://svn.apache.org/repos/asf/river/river-rt-tools/trunk' and do
> a ‘mvn install’ on it, which will install the runtime tool artifacts
> (start.jar) in your local Maven cache. In the end, those artifacts
> would also be released and published on Maven Central, so you
> eventually wouldn’t need to build the runtime tools separately.
>
> My plan is to add modules to the river-examples project for a
> 'hello-service’ and ‘hello-client’, as well as a config for the
> infrastructure services (Reggie, etc). So eventually, the “getting
> started” instructions become “have a look at ‘river-examples’”, and
> we’d remove the (very confusing, if you ask me) ‘examples’ folder
> from the JTSK distribution. As a bonus, we can isolate new users
> from the convoluted build system in River.
>
> If this seems like a reasonable path forward for our “getting
> started” experience, perhaps you’d like to work on bringing over some
> of the examples from the JTSK to the ‘river-examples’ project. That’s
> probably also a good way to re-familiarize yourself with Jini. I
> probably won’t have any cycles to work on it seriously for the next
> couple weeks, but could cheerfully make suggestions.
>
> You should be able to check-out these two Maven project in the IDE of
> your choice. I was using NetBeans, but AFAIK, Eclipse should be able
> to use the Maven build directly. I just haven’t tried it.
>
> Cheers,
>
> Greg Trasuk.
>
> On Jan 5, 2015, at 6:07 PM, Patricia Shanahan <pa...@acm.org> wrote:
>
>> I have completed buying a new home, moving into it, and selling the
>> old one, followed by Christmas in England and recovery from the
>> cold I caught there. That means I'm ready to get much more active
>> in River.
>>
>> Last year, we got some feedback suggesting that better support for
>> new users might remove a barrier to community building. My main
>> agenda is community building, so I want to work on that. I am going
>> to be a very naive potential user, so stand by for basic
>> questions.
>>
>> I began by downloading the binary version, since in this mode I am
>> not interested in being a River developer. However, when I looked
>> at the "Getting Started" page,
>> river.apache.org/user-guide-basic-river-services.html, it says:
>>
>> "The instructions assume that you're building from source as
>> checked out from the SVN trunk. Currently this is necessary because
>> the code snippets below use methods and classes which, at time of
>> writing, haven't made it into the latest binary release yet. Having
>> said that, the code you will need in the binary release isn't to
>> far removed from what you'll see below, so you can progress with
>> the binary release if you want to and are happy odifying the
>> code."
>>
>> According to the page info, the "time of writing" was no later than
>> November 23, 2013. Do I still need to do a River build before I can
>> run the example? If so, why and what can I do to fix that?
>>
>> I have no idea whether or not I would be happy "odifying" code -
>> maybe "modifying"?
>>
>> What is the best procedure for editing the "Getting Started" page?
>> I want to make sure that any changes I make really are
>> improvements, so I would like PMC review as I go along.
>>
>> Patricia
>>
>>
>
Re: Getting Started
Posted by Patricia Shanahan <pa...@acm.org>.
In general, I agree with not telling people what build tool to use.
For "Getting Started" there is a trade-off. There does not seem to be
any one tool that dominates the way "make" dominated in the 1980's. No
matter what tool or tools we pick, some potential users will not be
familiar with any of them, so detailed instructions will be needed.
If we have the resources to create, fully document, and maintain
"Getting Started" examples in two or more tools, great. If not, I think
it would be better to have one approach really well documented than two
incomplete approaches.
Patricia
On 1/8/2015 2:21 PM, Greg Trasuk wrote:
>
> Hi Dennis:
>
> I’m slightly allergic to hard-and-fast conventions. For example, the
> service browser example really doesn’t fit those conventions. Also,
> I’m reticent to suggest repackaging the infrastructure services
> (reggie, outrigger, mahalo, etc) at this time (meaning that I
> personally have no plans to do it). Having said that, I’m basically
> with you. Matter of fact if you have a look at the River-Container
> examples over at https://github.com/trasukg/river-container-examples
> you’ll see that’s pretty much the same style. The minor difference
> is that I’ve used ‘hello-impl’ rather than ‘hello-service’, and
> there’s also a ‘hello-module’ that is the packaged artifact for the
> container.
>
> I believe the critical thing is to make sure that the client api is
> separate, so that the client doesn’t accidentally know anything about
> the implementation. All else is implementation details, though I
> agree that we should provide a good example.
>
> As far as Maven/Gradle, it happens that I know Maven and not Gradle.
> All I am trying to do is provide some easier example than just diving
> into the JTSK source. If someone were to contribute a Gradle-based
> example, that’s all-the-better for user choice. But I don’t think we
> should go around telling people what build tool to use.
>
> Cheers,
>
> Greg Trasuk
>
>
> On Jan 8, 2015, at 4:05 PM, Dennis Reedy <de...@gmail.com>
> wrote:
>
>> Hi Greg,
>>
>> I'd like to suggest that River follow the conventions that align
>> with whats recommended over in Rio
>> (http://www.rio-project.org/conventions.html). This has been pretty
>> successful using both Maven and Gradle (at this time I would go
>> with Gradle btw).
>>
>> HTH
>>
>> Regards
>>
>> Dennis
>>
>>> On Jan 5, 2015, at 1016PM, Greg Trasuk <tr...@stratuscom.com>
>>> wrote:
>>>
>>>
>>> I started working on making new demos and “getting started” stuff
>>> back before the holidays. Here’s my thinking…
>>>
>>> As Patricia alludes to, it really shouldn’t be necessary to build
>>> the River distribution in order to try out some samples and get
>>> started. After all, the artifacts are published on Maven
>>> Central, so they can simply be referenced in a Maven build (or
>>> Gradle, Ivy, Etc).
>>>
>>> Towards that end, I started building a new Mavenized ‘examples’
>>> project, which can be checked-out from
>>> https://svn.apache.org/repos/asf/river/river-examples/river-examples/trunk.
>>>
>>>
>>>
In that project, there are currently modules for the service browser
jars and a ‘home’ folder for the compiled and packaged examples. (might
be best to download it and do a ‘mvn install site’). There’s also
documentation for the examples under the main project (look at
<project-home>/target/site/index.html - this should be familiar to Maven
users). The documentation currently includes how to build and run the
service browser (although I think right now it’s incomplete on how the
configuration works - haven’t looked at it since Dec 15).
>>>
>>> Right now, the project has a dependency on the new
>>> ‘river-rt-tools’ modules that I talked about back in December as
>>> well. So in order to run the examples, you currently need to
>>> checkout
>>> 'https://svn.apache.org/repos/asf/river/river-rt-tools/trunk' and
>>> do a ‘mvn install’ on it, which will install the runtime tool
>>> artifacts (start.jar) in your local Maven cache. In the end,
>>> those artifacts would also be released and published on Maven
>>> Central, so you eventually wouldn’t need to build the runtime
>>> tools separately.
>>>
>>> My plan is to add modules to the river-examples project for a
>>> 'hello-service’ and ‘hello-client’, as well as a config for the
>>> infrastructure services (Reggie, etc). So eventually, the
>>> “getting started” instructions become “have a look at
>>> ‘river-examples’”, and we’d remove the (very confusing, if you
>>> ask me) ‘examples’ folder from the JTSK distribution. As a
>>> bonus, we can isolate new users from the convoluted build system
>>> in River.
>>>
>>> If this seems like a reasonable path forward for our “getting
>>> started” experience, perhaps you’d like to work on bringing over
>>> some of the examples from the JTSK to the ‘river-examples’
>>> project. That’s probably also a good way to re-familiarize
>>> yourself with Jini. I probably won’t have any cycles to work on
>>> it seriously for the next couple weeks, but could cheerfully make
>>> suggestions.
>>>
>>> You should be able to check-out these two Maven project in the
>>> IDE of your choice. I was using NetBeans, but AFAIK, Eclipse
>>> should be able to use the Maven build directly. I just haven’t
>>> tried it.
>>>
>>> Cheers,
>>>
>>> Greg Trasuk.
>>>
>>> On Jan 5, 2015, at 6:07 PM, Patricia Shanahan <pa...@acm.org>
>>> wrote:
>>>
>>>> I have completed buying a new home, moving into it, and selling
>>>> the old one, followed by Christmas in England and recovery from
>>>> the cold I caught there. That means I'm ready to get much more
>>>> active in River.
>>>>
>>>> Last year, we got some feedback suggesting that better support
>>>> for new users might remove a barrier to community building. My
>>>> main agenda is community building, so I want to work on that. I
>>>> am going to be a very naive potential user, so stand by for
>>>> basic questions.
>>>>
>>>> I began by downloading the binary version, since in this mode I
>>>> am not interested in being a River developer. However, when I
>>>> looked at the "Getting Started" page,
>>>> river.apache.org/user-guide-basic-river-services.html, it
>>>> says:
>>>>
>>>> "The instructions assume that you're building from source as
>>>> checked out from the SVN trunk. Currently this is necessary
>>>> because the code snippets below use methods and classes which,
>>>> at time of writing, haven't made it into the latest binary
>>>> release yet. Having said that, the code you will need in the
>>>> binary release isn't to far removed from what you'll see below,
>>>> so you can progress with the binary release if you want to and
>>>> are happy odifying the code."
>>>>
>>>> According to the page info, the "time of writing" was no later
>>>> than November 23, 2013. Do I still need to do a River build
>>>> before I can run the example? If so, why and what can I do to
>>>> fix that?
>>>>
>>>> I have no idea whether or not I would be happy "odifying" code
>>>> - maybe "modifying"?
>>>>
>>>> What is the best procedure for editing the "Getting Started"
>>>> page? I want to make sure that any changes I make really are
>>>> improvements, so I would like PMC review as I go along.
>>>>
>>>> Patricia
>>>>
>>>>
>>>
>>
>
Re: Getting Started
Posted by Patricia Shanahan <pa...@acm.org>.
I may be the only committer with the time to work on this right now. Is
that correct?
Patricia
On 1/8/2015 5:17 PM, Dennis Reedy wrote:
...
> What would be great would be to figure out what examples you want to
> provide (a distributed calculator example is a simple one), and just
> do it.
...
Re: Getting Started
Posted by Dennis Reedy <de...@gmail.com>.
Greg,
I guess I missed your link to that GitHub project, it looks like a really good start, nice job. Since you're going the Maven route, you should probably look into improving the poms to use dependencyManagement and pluginManagement(where needed). You'll want to put that in the parent pom.
I'm a little puzzled by the hello-module idea, as well as the test approach, doesn't seem like there is much there at this point, not sure what you had planned.
I'm no so sure that the Starter-based project is convoluted, its fairly straight forward. If the group would like, I'll be glad to spend a day creating a calculator example based on gradle that includes bootstrapping and testing using stock River with service starter bits.
Dennis
> On Jan 8, 2015, at 912PM, Greg Trasuk <tr...@stratuscom.com> wrote:
>
>
> On Jan 8, 2015, at 8:17 PM, Dennis Reedy <de...@gmail.com> wrote:
>
>>
>> I don't know if pushing your River container approach is best for an example, but a stock River example with straight forward conventions allows developers to understand how to structure a project, how to build it, and most importantly how to test it. Without those basic fundamentals of an example it doesn't make much sense to pursue.
>>
>
> I’m not pushing the river container here. The project in https://github.com/trasukg/river-container-examples is straight River, with the one caveat that (as we discussed on the list a few weeks ago) I have pulled out the old com.sun.jini.start package to a different project, which is at https://svn.apache.org/repos/asf/river/river-rt-tools/trunk', and renamed it to ‘org.apache.river.tools.rt.start’. I only mentioned the river container examples to show that we’re in basic agreement on how to structure a project that implements a service and client.
>
> Now if you ask me, the convoluted structure of a Starter-based project makes its own argument for a container, but that’s a whole different conversation.
>
> But in any case, I’ll try to add the actual client and service examples into the examples project in the next few days, and then I think you’ll see that we’re really not disagreeing very much. I’m planning on yer basic ‘hello-world’ service.
>
> Cheers,
>
> Greg Trasuk
Re: Getting Started
Posted by Greg Trasuk <tr...@stratuscom.com>.
Hi Dennis:
There is some work pending...The overall plan is like this:
- Show the browser, because the browser is useful. I agree that it’s a bad example, and frankly, I was shocked to find it was in the examples section of the JTSK (I long ago put it into separate module and forgot where it came from and how to build it). However the browser is great for seeing that you actually have some services deployed. This portion is not so much instructive example, as providing a utility. Also, it lets us begin to introduce the idea of policy files, configurations and the Service Starter.
(One could argue that you could just run the browser out of the JTSK directory. But I honestly think that a look at the JTSK will simply scare people off, and is unnecessary since we published to Central. I’ll repeat my assertion that the vast majority of people who write web apps have never compiled Tomcat or any other part of JEE).
- Add enough pieces to run the infrastructure services. Initially just Reggie, probably, but then whatever other services the examples need. You need the infrastructure after all, and this shows a little more about how configurations work, as well as the Service Starter.
- Add a service module, properly structured into API and implementation, as we’ve been talking about. Initially, this service is plain old Jeri, no authentication, etc.
- Add a client module that talks to that service. Type in your name, it calls the hello service, service responds with ‘hi there’.
- Would be kind of nice to have a web app client for the service too, but personally I was going to leave that for later.
- Add another configuration that adds-in SSL-based security. I suspect that this might be more instructive as a completely separate server and client. We’ll see how we feel when we get there.
The github links are basically the hello-world and its api and client, as implemented for the River Container project (hence the hello-module, not required for plain old River). I’ll likely just copy them over to ‘river-examples’. In the case of my container project, it doesn’t need the browser or infrastructure services, because they’re built and packaged with the container.
Anyhow, that’s where I’m going with this. The goal is to be able to say “Hey, you want that micro-service thing everybody’s talking about? Here’s how to do it with River”. And then point people to a set of well-documented examples.
I suspect it would be interesting to have an example with Gradle as well. Could that fit in with this project? My gut feel is that it might be confusing to have both build styles together. Perhaps you might want to wait til I have the other examples done, then port it? Should be pretty easy, since as you say, the module structure is probably similar.
Cheers,
Greg.
On Jan 8, 2015, at 11:34 PM, Dennis Reedy <de...@gmail.com> wrote:
> Greg,
>
> Wow, I really liked the other link(s) better. Are there commits pending? All I see is the browser, and I don't think the browser is at all a good reference for an example. Is that where you're going?
>
> Thanks
>
> Dennis
>
>> On Jan 8, 2015, at 916PM, Greg Trasuk <tr...@stratuscom.com> wrote:
>>
>> Misfired on the url below. The project at https://svn.apache.org/repos/asf/river/river-examples/river-examples/trunk is straight River, not the github url below.
>>
>> Cheers,
>>
>> Greg Trasuk
>>
>> On Jan 8, 2015, at 9:12 PM, Greg Trasuk <tr...@stratuscom.com> wrote:
>>
>>>
>>> On Jan 8, 2015, at 8:17 PM, Dennis Reedy <de...@gmail.com> wrote:
>>>
>>>>
>>>> I don't know if pushing your River container approach is best for an example, but a stock River example with straight forward conventions allows developers to understand how to structure a project, how to build it, and most importantly how to test it. Without those basic fundamentals of an example it doesn't make much sense to pursue.
>>>>
>>>
>>> I’m not pushing the river container here. The project in https://github.com/trasukg/river-container-examples is straight River, with the one caveat that (as we discussed on the list a few weeks ago) I have pulled out the old com.sun.jini.start package to a different project, which is at https://svn.apache.org/repos/asf/river/river-rt-tools/trunk', and renamed it to ‘org.apache.river.tools.rt.start’. I only mentioned the river container examples to show that we’re in basic agreement on how to structure a project that implements a service and client.
>>>
>>> Now if you ask me, the convoluted structure of a Starter-based project makes its own argument for a container, but that’s a whole different conversation.
>>>
>>> But in any case, I’ll try to add the actual client and service examples into the examples project in the next few days, and then I think you’ll see that we’re really not disagreeing very much. I’m planning on yer basic ‘hello-world’ service.
>>>
>>> Cheers,
>>>
>>> Greg Trasuk
>>
>
Re: Getting Started
Posted by Dennis Reedy <de...@gmail.com>.
Greg,
Wow, I really liked the other link(s) better. Are there commits pending? All I see is the browser, and I don't think the browser is at all a good reference for an example. Is that where you're going?
Thanks
Dennis
> On Jan 8, 2015, at 916PM, Greg Trasuk <tr...@stratuscom.com> wrote:
>
> Misfired on the url below. The project at https://svn.apache.org/repos/asf/river/river-examples/river-examples/trunk is straight River, not the github url below.
>
> Cheers,
>
> Greg Trasuk
>
> On Jan 8, 2015, at 9:12 PM, Greg Trasuk <tr...@stratuscom.com> wrote:
>
>>
>> On Jan 8, 2015, at 8:17 PM, Dennis Reedy <de...@gmail.com> wrote:
>>
>>>
>>> I don't know if pushing your River container approach is best for an example, but a stock River example with straight forward conventions allows developers to understand how to structure a project, how to build it, and most importantly how to test it. Without those basic fundamentals of an example it doesn't make much sense to pursue.
>>>
>>
>> I’m not pushing the river container here. The project in https://github.com/trasukg/river-container-examples is straight River, with the one caveat that (as we discussed on the list a few weeks ago) I have pulled out the old com.sun.jini.start package to a different project, which is at https://svn.apache.org/repos/asf/river/river-rt-tools/trunk', and renamed it to ‘org.apache.river.tools.rt.start’. I only mentioned the river container examples to show that we’re in basic agreement on how to structure a project that implements a service and client.
>>
>> Now if you ask me, the convoluted structure of a Starter-based project makes its own argument for a container, but that’s a whole different conversation.
>>
>> But in any case, I’ll try to add the actual client and service examples into the examples project in the next few days, and then I think you’ll see that we’re really not disagreeing very much. I’m planning on yer basic ‘hello-world’ service.
>>
>> Cheers,
>>
>> Greg Trasuk
>
Re: Getting Started
Posted by Greg Trasuk <tr...@stratuscom.com>.
Misfired on the url below. The project at https://svn.apache.org/repos/asf/river/river-examples/river-examples/trunk is straight River, not the github url below.
Cheers,
Greg Trasuk
On Jan 8, 2015, at 9:12 PM, Greg Trasuk <tr...@stratuscom.com> wrote:
>
> On Jan 8, 2015, at 8:17 PM, Dennis Reedy <de...@gmail.com> wrote:
>
>>
>> I don't know if pushing your River container approach is best for an example, but a stock River example with straight forward conventions allows developers to understand how to structure a project, how to build it, and most importantly how to test it. Without those basic fundamentals of an example it doesn't make much sense to pursue.
>>
>
> I’m not pushing the river container here. The project in https://github.com/trasukg/river-container-examples is straight River, with the one caveat that (as we discussed on the list a few weeks ago) I have pulled out the old com.sun.jini.start package to a different project, which is at https://svn.apache.org/repos/asf/river/river-rt-tools/trunk', and renamed it to ‘org.apache.river.tools.rt.start’. I only mentioned the river container examples to show that we’re in basic agreement on how to structure a project that implements a service and client.
>
> Now if you ask me, the convoluted structure of a Starter-based project makes its own argument for a container, but that’s a whole different conversation.
>
> But in any case, I’ll try to add the actual client and service examples into the examples project in the next few days, and then I think you’ll see that we’re really not disagreeing very much. I’m planning on yer basic ‘hello-world’ service.
>
> Cheers,
>
> Greg Trasuk
Re: Getting Started
Posted by Patricia Shanahan <pa...@acm.org>.
Excellent. What would be most useful for me to study for the next few days?
On 1/8/2015 6:12 PM, Greg Trasuk wrote:
...
> But in any case, I’ll try to add the actual client and service
> examples into the examples project in the next few days, and then I
> think you’ll see that we’re really not disagreeing very much. I’m
> planning on yer basic ‘hello-world’ service.
...
Re: Getting Started
Posted by Greg Trasuk <tr...@stratuscom.com>.
On Jan 8, 2015, at 8:17 PM, Dennis Reedy <de...@gmail.com> wrote:
>
> I don't know if pushing your River container approach is best for an example, but a stock River example with straight forward conventions allows developers to understand how to structure a project, how to build it, and most importantly how to test it. Without those basic fundamentals of an example it doesn't make much sense to pursue.
>
I’m not pushing the river container here. The project in https://github.com/trasukg/river-container-examples is straight River, with the one caveat that (as we discussed on the list a few weeks ago) I have pulled out the old com.sun.jini.start package to a different project, which is at https://svn.apache.org/repos/asf/river/river-rt-tools/trunk', and renamed it to ‘org.apache.river.tools.rt.start’. I only mentioned the river container examples to show that we’re in basic agreement on how to structure a project that implements a service and client.
Now if you ask me, the convoluted structure of a Starter-based project makes its own argument for a container, but that’s a whole different conversation.
But in any case, I’ll try to add the actual client and service examples into the examples project in the next few days, and then I think you’ll see that we’re really not disagreeing very much. I’m planning on yer basic ‘hello-world’ service.
Cheers,
Greg Trasuk
Re: Getting Started
Posted by Dennis Reedy <de...@gmail.com>.
Greg,
I included the links to the aforementioned work to provide examples of what you might be able to do wrt examples. I was hoping you could look at what has already been done both in River and Rio, and take advantage of it. I see how you could have misunderstood my reply, and heaven forbid we get into another rat hole of maven, ant, gradle, make or whatever...
What would be great would be to figure out what examples you want to provide (a distributed calculator example is a simple one), and just do it.
Its super easy to create project that can be built using Maven or Gradle (there are even project generation tools that do this for River/Rio), that is along as you adhere to some basic conventions (to which I have already mentioned). You need to also understand that conventions are never hard-and-fast, they are by definition a way in which something is usually done, it does not mean it is the only way, or "the" way, just a really good way that if followed will generally lead to an easier road to follow. I know this is a tough sell for this group, where most everybody has their way, and is unwilling to part from it, but my experience in making projects successful using River as a technology generally is based on de-mystifying it and making it straight forward. Reasonable conventions help with this.
I don't know if pushing your River container approach is best for an example, but a stock River example with straight forward conventions allows developers to understand how to structure a project, how to build it, and most importantly how to test it. Without those basic fundamentals of an example it doesn't make much sense to pursue.
For me, having spent years in the Maven world, and having done a huge project conversion that uses River from Ant to Gradle, Gradle would be my choice for an example. Maven is too complicated, to restrictive, and geez XML. Ughh. You can see from my earlier links that the project structure remains the same, the project automation tool changes. You get the same artifact resolution from Maven repositories, but a much much stronger, flexible project automation tool that we can do so much more with.
HTH
Dennis
> On Jan 8, 2015, at 557PM, Greg Trasuk <tr...@stratuscom.com> wrote:
>
>
> So, to be clear, I’m not talking about “Mavenizing” River. I’m not saying that’s a bad idea (or gradle-izing, whatever). But let’s face it - we’ve been talking about it for five years with no agreement and no progress.
>
> What we have is a build process for the River libraries in the JTSK that works (although it needs to get updated for JDK 8) but confuses the heck out of everyone. I think we all agree that something ought to be done, but we it’ll be a big job. The problem is, we keep allowing that argument to block any progress on our “getting started” experience.
>
> I have always been of the viewpoint that the vast majority of potential users of River really do not need to be concerned with compiling River. They just need the jars, and they need to know how to use them.
>
> So what I’m suggesting here, is a set of examples that show people how to use River to get the services up-and-running in a fresh build tool. Which we all know does not actually require anyone to build River, since the artifacts are in Central. If those users become interested in hacking on the River source, then they’re welcome to either learn how the JTSK build works, or fix it - that’s great. But that’s not what I’m talking about with these examples.
>
> I’m pointing this out in the hope that we avoid falling into another round of arguments over “modularizing” or “Mavenizing” River.
>
>
> Cheers,
>
> Greg Trasuk
>
>
> On Jan 8, 2015, at 5:31 PM, Dennis Reedy <de...@gmail.com> wrote:
>
>> Greg,
>>
>> Here is a start to a gradle-ized version of River done 3 years ago http://svn.apache.org/viewvc/river/jtsk/skunk/modules/, could easily beused to create examples as well.
>>
>> And here is the maven-ized version: http://svn.apache.org/viewvc/river/jtsk/skunk/qa_refactor/trunk/modularize/
>>
>> HTH
>>
>> Dennis
>>
>>> On Jan 8, 2015, at 521PM, Greg Trasuk <tr...@stratuscom.com> wrote:
>>>
>>>
>>> Hi Dennis:
>>>
>>> I’m slightly allergic to hard-and-fast conventions. For example, the service browser example really doesn’t fit those conventions. Also, I’m reticent to suggest repackaging the infrastructure services (reggie, outrigger, mahalo, etc) at this time (meaning that I personally have no plans to do it). Having said that, I’m basically with you. Matter of fact if you have a look at the River-Container examples over at https://github.com/trasukg/river-container-examples you’ll see that’s pretty much the same style. The minor difference is that I’ve used ‘hello-impl’ rather than ‘hello-service’, and there’s also a ‘hello-module’ that is the packaged artifact for the container.
>>>
>>> I believe the critical thing is to make sure that the client api is separate, so that the client doesn’t accidentally know anything about the implementation. All else is implementation details, though I agree that we should provide a good example.
>>>
>>> As far as Maven/Gradle, it happens that I know Maven and not Gradle. All I am trying to do is provide some easier example than just diving into the JTSK source. If someone were to contribute a Gradle-based example, that’s all-the-better for user choice. But I don’t think we should go around telling people what build tool to use.
>>>
>>> Cheers,
>>>
>>> Greg Trasuk
>>>
>>>
>>> On Jan 8, 2015, at 4:05 PM, Dennis Reedy <de...@gmail.com> wrote:
>>>
>>>> Hi Greg,
>>>>
>>>> I'd like to suggest that River follow the conventions that align with whats recommended over in Rio (http://www.rio-project.org/conventions.html). This has been pretty successful using both Maven and Gradle (at this time I would go with Gradle btw).
>>>>
>>>> HTH
>>>>
>>>> Regards
>>>>
>>>> Dennis
>>>>
>>>>> On Jan 5, 2015, at 1016PM, Greg Trasuk <tr...@stratuscom.com> wrote:
>>>>>
>>>>>
>>>>> I started working on making new demos and “getting started” stuff back before the holidays. Here’s my thinking…
>>>>>
>>>>> As Patricia alludes to, it really shouldn’t be necessary to build the River distribution in order to try out some samples and get started. After all, the artifacts are published on Maven Central, so they can simply be referenced in a Maven build (or Gradle, Ivy, Etc).
>>>>>
>>>>> Towards that end, I started building a new Mavenized ‘examples’ project, which can be checked-out from https://svn.apache.org/repos/asf/river/river-examples/river-examples/trunk.
>>>>>
>>>>> In that project, there are currently modules for the service browser jars and a ‘home’ folder for the compiled and packaged examples. (might be best to download it and do a ‘mvn install site’). There’s also documentation for the examples under the main project (look at <project-home>/target/site/index.html - this should be familiar to Maven users). The documentation currently includes how to build and run the service browser (although I think right now it’s incomplete on how the configuration works - haven’t looked at it since Dec 15).
>>>>>
>>>>> Right now, the project has a dependency on the new ‘river-rt-tools’ modules that I talked about back in December as well. So in order to run the examples, you currently need to checkout 'https://svn.apache.org/repos/asf/river/river-rt-tools/trunk' and do a ‘mvn install’ on it, which will install the runtime tool artifacts (start.jar) in your local Maven cache. In the end, those artifacts would also be released and published on Maven Central, so you eventually wouldn’t need to build the runtime tools separately.
>>>>>
>>>>> My plan is to add modules to the river-examples project for a 'hello-service’ and ‘hello-client’, as well as a config for the infrastructure services (Reggie, etc). So eventually, the “getting started” instructions become “have a look at ‘river-examples’”, and we’d remove the (very confusing, if you ask me) ‘examples’ folder from the JTSK distribution. As a bonus, we can isolate new users from the convoluted build system in River.
>>>>>
>>>>> If this seems like a reasonable path forward for our “getting started” experience, perhaps you’d like to work on bringing over some of the examples from the JTSK to the ‘river-examples’ project. That’s probably also a good way to re-familiarize yourself with Jini. I probably won’t have any cycles to work on it seriously for the next couple weeks, but could cheerfully make suggestions.
>>>>>
>>>>> You should be able to check-out these two Maven project in the IDE of your choice. I was using NetBeans, but AFAIK, Eclipse should be able to use the Maven build directly. I just haven’t tried it.
>>>>>
>>>>> Cheers,
>>>>>
>>>>> Greg Trasuk.
>>>>>
>>>>> On Jan 5, 2015, at 6:07 PM, Patricia Shanahan <pa...@acm.org> wrote:
>>>>>
>>>>>> I have completed buying a new home, moving into it, and selling the old one, followed by Christmas in England and recovery from the cold I caught there. That means I'm ready to get much more active in River.
>>>>>>
>>>>>> Last year, we got some feedback suggesting that better support for new users might remove a barrier to community building. My main agenda is community building, so I want to work on that. I am going to be a very naive potential user, so stand by for basic questions.
>>>>>>
>>>>>> I began by downloading the binary version, since in this mode I am not interested in being a River developer. However, when I looked at the "Getting Started" page, river.apache.org/user-guide-basic-river-services.html, it says:
>>>>>>
>>>>>> "The instructions assume that you're building from source as checked out from the SVN trunk. Currently this is necessary because the code snippets below use methods and classes which, at time of writing, haven't made it into the latest binary release yet. Having said that, the code you will need in the binary release isn't to far removed from what you'll see below, so you can progress with the binary release if you want to and are happy odifying the code."
>>>>>>
>>>>>> According to the page info, the "time of writing" was no later than November 23, 2013. Do I still need to do a River build before I can run the example? If so, why and what can I do to fix that?
>>>>>>
>>>>>> I have no idea whether or not I would be happy "odifying" code - maybe "modifying"?
>>>>>>
>>>>>> What is the best procedure for editing the "Getting Started" page? I want to make sure that any changes I make really are improvements, so I would like PMC review as I go along.
>>>>>>
>>>>>> Patricia
>>>>>>
>>>>>>
>>>>>
>>>>
>>>
>>
>
Re: Getting Started
Posted by Greg Trasuk <tr...@stratuscom.com>.
So, to be clear, I’m not talking about “Mavenizing” River. I’m not saying that’s a bad idea (or gradle-izing, whatever). But let’s face it - we’ve been talking about it for five years with no agreement and no progress.
What we have is a build process for the River libraries in the JTSK that works (although it needs to get updated for JDK 8) but confuses the heck out of everyone. I think we all agree that something ought to be done, but we it’ll be a big job. The problem is, we keep allowing that argument to block any progress on our “getting started” experience.
I have always been of the viewpoint that the vast majority of potential users of River really do not need to be concerned with compiling River. They just need the jars, and they need to know how to use them.
So what I’m suggesting here, is a set of examples that show people how to use River to get the services up-and-running in a fresh build tool. Which we all know does not actually require anyone to build River, since the artifacts are in Central. If those users become interested in hacking on the River source, then they’re welcome to either learn how the JTSK build works, or fix it - that’s great. But that’s not what I’m talking about with these examples.
I’m pointing this out in the hope that we avoid falling into another round of arguments over “modularizing” or “Mavenizing” River.
Cheers,
Greg Trasuk
On Jan 8, 2015, at 5:31 PM, Dennis Reedy <de...@gmail.com> wrote:
> Greg,
>
> Here is a start to a gradle-ized version of River done 3 years ago http://svn.apache.org/viewvc/river/jtsk/skunk/modules/, could easily beused to create examples as well.
>
> And here is the maven-ized version: http://svn.apache.org/viewvc/river/jtsk/skunk/qa_refactor/trunk/modularize/
>
> HTH
>
> Dennis
>
>> On Jan 8, 2015, at 521PM, Greg Trasuk <tr...@stratuscom.com> wrote:
>>
>>
>> Hi Dennis:
>>
>> I’m slightly allergic to hard-and-fast conventions. For example, the service browser example really doesn’t fit those conventions. Also, I’m reticent to suggest repackaging the infrastructure services (reggie, outrigger, mahalo, etc) at this time (meaning that I personally have no plans to do it). Having said that, I’m basically with you. Matter of fact if you have a look at the River-Container examples over at https://github.com/trasukg/river-container-examples you’ll see that’s pretty much the same style. The minor difference is that I’ve used ‘hello-impl’ rather than ‘hello-service’, and there’s also a ‘hello-module’ that is the packaged artifact for the container.
>>
>> I believe the critical thing is to make sure that the client api is separate, so that the client doesn’t accidentally know anything about the implementation. All else is implementation details, though I agree that we should provide a good example.
>>
>> As far as Maven/Gradle, it happens that I know Maven and not Gradle. All I am trying to do is provide some easier example than just diving into the JTSK source. If someone were to contribute a Gradle-based example, that’s all-the-better for user choice. But I don’t think we should go around telling people what build tool to use.
>>
>> Cheers,
>>
>> Greg Trasuk
>>
>>
>> On Jan 8, 2015, at 4:05 PM, Dennis Reedy <de...@gmail.com> wrote:
>>
>>> Hi Greg,
>>>
>>> I'd like to suggest that River follow the conventions that align with whats recommended over in Rio (http://www.rio-project.org/conventions.html). This has been pretty successful using both Maven and Gradle (at this time I would go with Gradle btw).
>>>
>>> HTH
>>>
>>> Regards
>>>
>>> Dennis
>>>
>>>> On Jan 5, 2015, at 1016PM, Greg Trasuk <tr...@stratuscom.com> wrote:
>>>>
>>>>
>>>> I started working on making new demos and “getting started” stuff back before the holidays. Here’s my thinking…
>>>>
>>>> As Patricia alludes to, it really shouldn’t be necessary to build the River distribution in order to try out some samples and get started. After all, the artifacts are published on Maven Central, so they can simply be referenced in a Maven build (or Gradle, Ivy, Etc).
>>>>
>>>> Towards that end, I started building a new Mavenized ‘examples’ project, which can be checked-out from https://svn.apache.org/repos/asf/river/river-examples/river-examples/trunk.
>>>>
>>>> In that project, there are currently modules for the service browser jars and a ‘home’ folder for the compiled and packaged examples. (might be best to download it and do a ‘mvn install site’). There’s also documentation for the examples under the main project (look at <project-home>/target/site/index.html - this should be familiar to Maven users). The documentation currently includes how to build and run the service browser (although I think right now it’s incomplete on how the configuration works - haven’t looked at it since Dec 15).
>>>>
>>>> Right now, the project has a dependency on the new ‘river-rt-tools’ modules that I talked about back in December as well. So in order to run the examples, you currently need to checkout 'https://svn.apache.org/repos/asf/river/river-rt-tools/trunk' and do a ‘mvn install’ on it, which will install the runtime tool artifacts (start.jar) in your local Maven cache. In the end, those artifacts would also be released and published on Maven Central, so you eventually wouldn’t need to build the runtime tools separately.
>>>>
>>>> My plan is to add modules to the river-examples project for a 'hello-service’ and ‘hello-client’, as well as a config for the infrastructure services (Reggie, etc). So eventually, the “getting started” instructions become “have a look at ‘river-examples’”, and we’d remove the (very confusing, if you ask me) ‘examples’ folder from the JTSK distribution. As a bonus, we can isolate new users from the convoluted build system in River.
>>>>
>>>> If this seems like a reasonable path forward for our “getting started” experience, perhaps you’d like to work on bringing over some of the examples from the JTSK to the ‘river-examples’ project. That’s probably also a good way to re-familiarize yourself with Jini. I probably won’t have any cycles to work on it seriously for the next couple weeks, but could cheerfully make suggestions.
>>>>
>>>> You should be able to check-out these two Maven project in the IDE of your choice. I was using NetBeans, but AFAIK, Eclipse should be able to use the Maven build directly. I just haven’t tried it.
>>>>
>>>> Cheers,
>>>>
>>>> Greg Trasuk.
>>>>
>>>> On Jan 5, 2015, at 6:07 PM, Patricia Shanahan <pa...@acm.org> wrote:
>>>>
>>>>> I have completed buying a new home, moving into it, and selling the old one, followed by Christmas in England and recovery from the cold I caught there. That means I'm ready to get much more active in River.
>>>>>
>>>>> Last year, we got some feedback suggesting that better support for new users might remove a barrier to community building. My main agenda is community building, so I want to work on that. I am going to be a very naive potential user, so stand by for basic questions.
>>>>>
>>>>> I began by downloading the binary version, since in this mode I am not interested in being a River developer. However, when I looked at the "Getting Started" page, river.apache.org/user-guide-basic-river-services.html, it says:
>>>>>
>>>>> "The instructions assume that you're building from source as checked out from the SVN trunk. Currently this is necessary because the code snippets below use methods and classes which, at time of writing, haven't made it into the latest binary release yet. Having said that, the code you will need in the binary release isn't to far removed from what you'll see below, so you can progress with the binary release if you want to and are happy odifying the code."
>>>>>
>>>>> According to the page info, the "time of writing" was no later than November 23, 2013. Do I still need to do a River build before I can run the example? If so, why and what can I do to fix that?
>>>>>
>>>>> I have no idea whether or not I would be happy "odifying" code - maybe "modifying"?
>>>>>
>>>>> What is the best procedure for editing the "Getting Started" page? I want to make sure that any changes I make really are improvements, so I would like PMC review as I go along.
>>>>>
>>>>> Patricia
>>>>>
>>>>>
>>>>
>>>
>>
>
Re: Getting Started
Posted by Dennis Reedy <de...@gmail.com>.
Greg,
Here is a start to a gradle-ized version of River done 3 years ago http://svn.apache.org/viewvc/river/jtsk/skunk/modules/, could easily beused to create examples as well.
And here is the maven-ized version: http://svn.apache.org/viewvc/river/jtsk/skunk/qa_refactor/trunk/modularize/
HTH
Dennis
> On Jan 8, 2015, at 521PM, Greg Trasuk <tr...@stratuscom.com> wrote:
>
>
> Hi Dennis:
>
> I’m slightly allergic to hard-and-fast conventions. For example, the service browser example really doesn’t fit those conventions. Also, I’m reticent to suggest repackaging the infrastructure services (reggie, outrigger, mahalo, etc) at this time (meaning that I personally have no plans to do it). Having said that, I’m basically with you. Matter of fact if you have a look at the River-Container examples over at https://github.com/trasukg/river-container-examples you’ll see that’s pretty much the same style. The minor difference is that I’ve used ‘hello-impl’ rather than ‘hello-service’, and there’s also a ‘hello-module’ that is the packaged artifact for the container.
>
> I believe the critical thing is to make sure that the client api is separate, so that the client doesn’t accidentally know anything about the implementation. All else is implementation details, though I agree that we should provide a good example.
>
> As far as Maven/Gradle, it happens that I know Maven and not Gradle. All I am trying to do is provide some easier example than just diving into the JTSK source. If someone were to contribute a Gradle-based example, that’s all-the-better for user choice. But I don’t think we should go around telling people what build tool to use.
>
> Cheers,
>
> Greg Trasuk
>
>
> On Jan 8, 2015, at 4:05 PM, Dennis Reedy <de...@gmail.com> wrote:
>
>> Hi Greg,
>>
>> I'd like to suggest that River follow the conventions that align with whats recommended over in Rio (http://www.rio-project.org/conventions.html). This has been pretty successful using both Maven and Gradle (at this time I would go with Gradle btw).
>>
>> HTH
>>
>> Regards
>>
>> Dennis
>>
>>> On Jan 5, 2015, at 1016PM, Greg Trasuk <tr...@stratuscom.com> wrote:
>>>
>>>
>>> I started working on making new demos and “getting started” stuff back before the holidays. Here’s my thinking…
>>>
>>> As Patricia alludes to, it really shouldn’t be necessary to build the River distribution in order to try out some samples and get started. After all, the artifacts are published on Maven Central, so they can simply be referenced in a Maven build (or Gradle, Ivy, Etc).
>>>
>>> Towards that end, I started building a new Mavenized ‘examples’ project, which can be checked-out from https://svn.apache.org/repos/asf/river/river-examples/river-examples/trunk.
>>>
>>> In that project, there are currently modules for the service browser jars and a ‘home’ folder for the compiled and packaged examples. (might be best to download it and do a ‘mvn install site’). There’s also documentation for the examples under the main project (look at <project-home>/target/site/index.html - this should be familiar to Maven users). The documentation currently includes how to build and run the service browser (although I think right now it’s incomplete on how the configuration works - haven’t looked at it since Dec 15).
>>>
>>> Right now, the project has a dependency on the new ‘river-rt-tools’ modules that I talked about back in December as well. So in order to run the examples, you currently need to checkout 'https://svn.apache.org/repos/asf/river/river-rt-tools/trunk' and do a ‘mvn install’ on it, which will install the runtime tool artifacts (start.jar) in your local Maven cache. In the end, those artifacts would also be released and published on Maven Central, so you eventually wouldn’t need to build the runtime tools separately.
>>>
>>> My plan is to add modules to the river-examples project for a 'hello-service’ and ‘hello-client’, as well as a config for the infrastructure services (Reggie, etc). So eventually, the “getting started” instructions become “have a look at ‘river-examples’”, and we’d remove the (very confusing, if you ask me) ‘examples’ folder from the JTSK distribution. As a bonus, we can isolate new users from the convoluted build system in River.
>>>
>>> If this seems like a reasonable path forward for our “getting started” experience, perhaps you’d like to work on bringing over some of the examples from the JTSK to the ‘river-examples’ project. That’s probably also a good way to re-familiarize yourself with Jini. I probably won’t have any cycles to work on it seriously for the next couple weeks, but could cheerfully make suggestions.
>>>
>>> You should be able to check-out these two Maven project in the IDE of your choice. I was using NetBeans, but AFAIK, Eclipse should be able to use the Maven build directly. I just haven’t tried it.
>>>
>>> Cheers,
>>>
>>> Greg Trasuk.
>>>
>>> On Jan 5, 2015, at 6:07 PM, Patricia Shanahan <pa...@acm.org> wrote:
>>>
>>>> I have completed buying a new home, moving into it, and selling the old one, followed by Christmas in England and recovery from the cold I caught there. That means I'm ready to get much more active in River.
>>>>
>>>> Last year, we got some feedback suggesting that better support for new users might remove a barrier to community building. My main agenda is community building, so I want to work on that. I am going to be a very naive potential user, so stand by for basic questions.
>>>>
>>>> I began by downloading the binary version, since in this mode I am not interested in being a River developer. However, when I looked at the "Getting Started" page, river.apache.org/user-guide-basic-river-services.html, it says:
>>>>
>>>> "The instructions assume that you're building from source as checked out from the SVN trunk. Currently this is necessary because the code snippets below use methods and classes which, at time of writing, haven't made it into the latest binary release yet. Having said that, the code you will need in the binary release isn't to far removed from what you'll see below, so you can progress with the binary release if you want to and are happy odifying the code."
>>>>
>>>> According to the page info, the "time of writing" was no later than November 23, 2013. Do I still need to do a River build before I can run the example? If so, why and what can I do to fix that?
>>>>
>>>> I have no idea whether or not I would be happy "odifying" code - maybe "modifying"?
>>>>
>>>> What is the best procedure for editing the "Getting Started" page? I want to make sure that any changes I make really are improvements, so I would like PMC review as I go along.
>>>>
>>>> Patricia
>>>>
>>>>
>>>
>>
>
Re: Getting Started
Posted by Greg Trasuk <tr...@stratuscom.com>.
Hi Dennis:
I’m slightly allergic to hard-and-fast conventions. For example, the service browser example really doesn’t fit those conventions. Also, I’m reticent to suggest repackaging the infrastructure services (reggie, outrigger, mahalo, etc) at this time (meaning that I personally have no plans to do it). Having said that, I’m basically with you. Matter of fact if you have a look at the River-Container examples over at https://github.com/trasukg/river-container-examples you’ll see that’s pretty much the same style. The minor difference is that I’ve used ‘hello-impl’ rather than ‘hello-service’, and there’s also a ‘hello-module’ that is the packaged artifact for the container.
I believe the critical thing is to make sure that the client api is separate, so that the client doesn’t accidentally know anything about the implementation. All else is implementation details, though I agree that we should provide a good example.
As far as Maven/Gradle, it happens that I know Maven and not Gradle. All I am trying to do is provide some easier example than just diving into the JTSK source. If someone were to contribute a Gradle-based example, that’s all-the-better for user choice. But I don’t think we should go around telling people what build tool to use.
Cheers,
Greg Trasuk
On Jan 8, 2015, at 4:05 PM, Dennis Reedy <de...@gmail.com> wrote:
> Hi Greg,
>
> I'd like to suggest that River follow the conventions that align with whats recommended over in Rio (http://www.rio-project.org/conventions.html). This has been pretty successful using both Maven and Gradle (at this time I would go with Gradle btw).
>
> HTH
>
> Regards
>
> Dennis
>
>> On Jan 5, 2015, at 1016PM, Greg Trasuk <tr...@stratuscom.com> wrote:
>>
>>
>> I started working on making new demos and “getting started” stuff back before the holidays. Here’s my thinking…
>>
>> As Patricia alludes to, it really shouldn’t be necessary to build the River distribution in order to try out some samples and get started. After all, the artifacts are published on Maven Central, so they can simply be referenced in a Maven build (or Gradle, Ivy, Etc).
>>
>> Towards that end, I started building a new Mavenized ‘examples’ project, which can be checked-out from https://svn.apache.org/repos/asf/river/river-examples/river-examples/trunk.
>>
>> In that project, there are currently modules for the service browser jars and a ‘home’ folder for the compiled and packaged examples. (might be best to download it and do a ‘mvn install site’). There’s also documentation for the examples under the main project (look at <project-home>/target/site/index.html - this should be familiar to Maven users). The documentation currently includes how to build and run the service browser (although I think right now it’s incomplete on how the configuration works - haven’t looked at it since Dec 15).
>>
>> Right now, the project has a dependency on the new ‘river-rt-tools’ modules that I talked about back in December as well. So in order to run the examples, you currently need to checkout 'https://svn.apache.org/repos/asf/river/river-rt-tools/trunk' and do a ‘mvn install’ on it, which will install the runtime tool artifacts (start.jar) in your local Maven cache. In the end, those artifacts would also be released and published on Maven Central, so you eventually wouldn’t need to build the runtime tools separately.
>>
>> My plan is to add modules to the river-examples project for a 'hello-service’ and ‘hello-client’, as well as a config for the infrastructure services (Reggie, etc). So eventually, the “getting started” instructions become “have a look at ‘river-examples’”, and we’d remove the (very confusing, if you ask me) ‘examples’ folder from the JTSK distribution. As a bonus, we can isolate new users from the convoluted build system in River.
>>
>> If this seems like a reasonable path forward for our “getting started” experience, perhaps you’d like to work on bringing over some of the examples from the JTSK to the ‘river-examples’ project. That’s probably also a good way to re-familiarize yourself with Jini. I probably won’t have any cycles to work on it seriously for the next couple weeks, but could cheerfully make suggestions.
>>
>> You should be able to check-out these two Maven project in the IDE of your choice. I was using NetBeans, but AFAIK, Eclipse should be able to use the Maven build directly. I just haven’t tried it.
>>
>> Cheers,
>>
>> Greg Trasuk.
>>
>> On Jan 5, 2015, at 6:07 PM, Patricia Shanahan <pa...@acm.org> wrote:
>>
>>> I have completed buying a new home, moving into it, and selling the old one, followed by Christmas in England and recovery from the cold I caught there. That means I'm ready to get much more active in River.
>>>
>>> Last year, we got some feedback suggesting that better support for new users might remove a barrier to community building. My main agenda is community building, so I want to work on that. I am going to be a very naive potential user, so stand by for basic questions.
>>>
>>> I began by downloading the binary version, since in this mode I am not interested in being a River developer. However, when I looked at the "Getting Started" page, river.apache.org/user-guide-basic-river-services.html, it says:
>>>
>>> "The instructions assume that you're building from source as checked out from the SVN trunk. Currently this is necessary because the code snippets below use methods and classes which, at time of writing, haven't made it into the latest binary release yet. Having said that, the code you will need in the binary release isn't to far removed from what you'll see below, so you can progress with the binary release if you want to and are happy odifying the code."
>>>
>>> According to the page info, the "time of writing" was no later than November 23, 2013. Do I still need to do a River build before I can run the example? If so, why and what can I do to fix that?
>>>
>>> I have no idea whether or not I would be happy "odifying" code - maybe "modifying"?
>>>
>>> What is the best procedure for editing the "Getting Started" page? I want to make sure that any changes I make really are improvements, so I would like PMC review as I go along.
>>>
>>> Patricia
>>>
>>>
>>
>
Re: Getting Started
Posted by Dennis Reedy <de...@gmail.com>.
Hi Greg,
I'd like to suggest that River follow the conventions that align with whats recommended over in Rio (http://www.rio-project.org/conventions.html). This has been pretty successful using both Maven and Gradle (at this time I would go with Gradle btw).
HTH
Regards
Dennis
> On Jan 5, 2015, at 1016PM, Greg Trasuk <tr...@stratuscom.com> wrote:
>
>
> I started working on making new demos and “getting started” stuff back before the holidays. Here’s my thinking…
>
> As Patricia alludes to, it really shouldn’t be necessary to build the River distribution in order to try out some samples and get started. After all, the artifacts are published on Maven Central, so they can simply be referenced in a Maven build (or Gradle, Ivy, Etc).
>
> Towards that end, I started building a new Mavenized ‘examples’ project, which can be checked-out from https://svn.apache.org/repos/asf/river/river-examples/river-examples/trunk.
>
> In that project, there are currently modules for the service browser jars and a ‘home’ folder for the compiled and packaged examples. (might be best to download it and do a ‘mvn install site’). There’s also documentation for the examples under the main project (look at <project-home>/target/site/index.html - this should be familiar to Maven users). The documentation currently includes how to build and run the service browser (although I think right now it’s incomplete on how the configuration works - haven’t looked at it since Dec 15).
>
> Right now, the project has a dependency on the new ‘river-rt-tools’ modules that I talked about back in December as well. So in order to run the examples, you currently need to checkout 'https://svn.apache.org/repos/asf/river/river-rt-tools/trunk' and do a ‘mvn install’ on it, which will install the runtime tool artifacts (start.jar) in your local Maven cache. In the end, those artifacts would also be released and published on Maven Central, so you eventually wouldn’t need to build the runtime tools separately.
>
> My plan is to add modules to the river-examples project for a 'hello-service’ and ‘hello-client’, as well as a config for the infrastructure services (Reggie, etc). So eventually, the “getting started” instructions become “have a look at ‘river-examples’”, and we’d remove the (very confusing, if you ask me) ‘examples’ folder from the JTSK distribution. As a bonus, we can isolate new users from the convoluted build system in River.
>
> If this seems like a reasonable path forward for our “getting started” experience, perhaps you’d like to work on bringing over some of the examples from the JTSK to the ‘river-examples’ project. That’s probably also a good way to re-familiarize yourself with Jini. I probably won’t have any cycles to work on it seriously for the next couple weeks, but could cheerfully make suggestions.
>
> You should be able to check-out these two Maven project in the IDE of your choice. I was using NetBeans, but AFAIK, Eclipse should be able to use the Maven build directly. I just haven’t tried it.
>
> Cheers,
>
> Greg Trasuk.
>
> On Jan 5, 2015, at 6:07 PM, Patricia Shanahan <pa...@acm.org> wrote:
>
>> I have completed buying a new home, moving into it, and selling the old one, followed by Christmas in England and recovery from the cold I caught there. That means I'm ready to get much more active in River.
>>
>> Last year, we got some feedback suggesting that better support for new users might remove a barrier to community building. My main agenda is community building, so I want to work on that. I am going to be a very naive potential user, so stand by for basic questions.
>>
>> I began by downloading the binary version, since in this mode I am not interested in being a River developer. However, when I looked at the "Getting Started" page, river.apache.org/user-guide-basic-river-services.html, it says:
>>
>> "The instructions assume that you're building from source as checked out from the SVN trunk. Currently this is necessary because the code snippets below use methods and classes which, at time of writing, haven't made it into the latest binary release yet. Having said that, the code you will need in the binary release isn't to far removed from what you'll see below, so you can progress with the binary release if you want to and are happy odifying the code."
>>
>> According to the page info, the "time of writing" was no later than November 23, 2013. Do I still need to do a River build before I can run the example? If so, why and what can I do to fix that?
>>
>> I have no idea whether or not I would be happy "odifying" code - maybe "modifying"?
>>
>> What is the best procedure for editing the "Getting Started" page? I want to make sure that any changes I make really are improvements, so I would like PMC review as I go along.
>>
>> Patricia
>>
>>
>
Re: Getting Started
Posted by Greg Trasuk <tr...@stratuscom.com>.
I started working on making new demos and “getting started” stuff back before the holidays. Here’s my thinking…
As Patricia alludes to, it really shouldn’t be necessary to build the River distribution in order to try out some samples and get started. After all, the artifacts are published on Maven Central, so they can simply be referenced in a Maven build (or Gradle, Ivy, Etc).
Towards that end, I started building a new Mavenized ‘examples’ project, which can be checked-out from https://svn.apache.org/repos/asf/river/river-examples/river-examples/trunk.
In that project, there are currently modules for the service browser jars and a ‘home’ folder for the compiled and packaged examples. (might be best to download it and do a ‘mvn install site’). There’s also documentation for the examples under the main project (look at <project-home>/target/site/index.html - this should be familiar to Maven users). The documentation currently includes how to build and run the service browser (although I think right now it’s incomplete on how the configuration works - haven’t looked at it since Dec 15).
Right now, the project has a dependency on the new ‘river-rt-tools’ modules that I talked about back in December as well. So in order to run the examples, you currently need to checkout 'https://svn.apache.org/repos/asf/river/river-rt-tools/trunk' and do a ‘mvn install’ on it, which will install the runtime tool artifacts (start.jar) in your local Maven cache. In the end, those artifacts would also be released and published on Maven Central, so you eventually wouldn’t need to build the runtime tools separately.
My plan is to add modules to the river-examples project for a 'hello-service’ and ‘hello-client’, as well as a config for the infrastructure services (Reggie, etc). So eventually, the “getting started” instructions become “have a look at ‘river-examples’”, and we’d remove the (very confusing, if you ask me) ‘examples’ folder from the JTSK distribution. As a bonus, we can isolate new users from the convoluted build system in River.
If this seems like a reasonable path forward for our “getting started” experience, perhaps you’d like to work on bringing over some of the examples from the JTSK to the ‘river-examples’ project. That’s probably also a good way to re-familiarize yourself with Jini. I probably won’t have any cycles to work on it seriously for the next couple weeks, but could cheerfully make suggestions.
You should be able to check-out these two Maven project in the IDE of your choice. I was using NetBeans, but AFAIK, Eclipse should be able to use the Maven build directly. I just haven’t tried it.
Cheers,
Greg Trasuk.
On Jan 5, 2015, at 6:07 PM, Patricia Shanahan <pa...@acm.org> wrote:
> I have completed buying a new home, moving into it, and selling the old one, followed by Christmas in England and recovery from the cold I caught there. That means I'm ready to get much more active in River.
>
> Last year, we got some feedback suggesting that better support for new users might remove a barrier to community building. My main agenda is community building, so I want to work on that. I am going to be a very naive potential user, so stand by for basic questions.
>
> I began by downloading the binary version, since in this mode I am not interested in being a River developer. However, when I looked at the "Getting Started" page, river.apache.org/user-guide-basic-river-services.html, it says:
>
> "The instructions assume that you're building from source as checked out from the SVN trunk. Currently this is necessary because the code snippets below use methods and classes which, at time of writing, haven't made it into the latest binary release yet. Having said that, the code you will need in the binary release isn't to far removed from what you'll see below, so you can progress with the binary release if you want to and are happy odifying the code."
>
> According to the page info, the "time of writing" was no later than November 23, 2013. Do I still need to do a River build before I can run the example? If so, why and what can I do to fix that?
>
> I have no idea whether or not I would be happy "odifying" code - maybe "modifying"?
>
> What is the best procedure for editing the "Getting Started" page? I want to make sure that any changes I make really are improvements, so I would like PMC review as I go along.
>
> Patricia
>
>