[p4] Java interface to Perforce / P4API for Java

[Dan Harmer]

Greetings from a Perforce newbie on a tight deadline,

I've been looking at the Perforce API and Python examples; however, I'm not
experienced in C/C++ and have had difficulty figuring out how to utilize it
via business rules (java classes) in our system. A perforce contact
mentioned that a guy named Michael Bishop has written a partial Java API for
perforce--does anyone on this list have any experience with this?

I checked out the source under the guest area of the depot and got
everything to compile, but don't really know where to start to try and
implement some of the methods. Does anyone have any sample implementations
or snippets of code that could serve as an example for me? I'm also new to
JNI, which appears to be heavily utilized in the C/C++ classes accompanying
the API. Could you please tell me what I need to do with those classes in
order to make everything work? What are the files in the macos folder for?
(jclientapi.exp, p4.macos.prefix.h, etc)

I am currently looking for the easiest way allow our system to utilize
Perforce's vaulting/SCM capabilities. For example, at the simplest level,
say we've got a JSP page with buttons that allow a user to checkin and
checkout files (such as source code, word docs, images, etc). What would be
the easiest way to trigger these actions in Perforce? Eventually, I also
want the capability to monitor changes within Perforce and trigger
additional business rules--such as sending an email to someone when a
document revision occurs by another user in the system.

For me, it seemed the easiest way to accomplish this might be using this
Java API; however, I know there are some plugins, command-line interfaces,
etc that might be just as easy or easier. Any guidance or suggestions would
be greatly appreciated as this is all new to me. Thanks,

Dan Harmer
***@xtendsoft.com

[Jeff A. Bowles]

[Sending a copy to perforce-user, since I think that these URLs are
particularly useful. And "yes, the command-line interface is so
robust and easy to use that I would NOT bother with the C++ API
for any sort of build needs, ever. For linking against an application
written in C++ that does other stuff, maybe; for Perl/shell/Python
sorts of scripts, the command-line's great!" -jab]

At 12:32 PM 10/30/2001 -0700, you wrote:
>Thanks for your response Jeff--I'll look into it. Do you know if the
>command-line interface is very robust?

VERY robust. You'll find FAQs at
http://public.perforce.com/public/perforce/faq/index.html
The build one is
http://public.perforce.com/public/perforce/faq/build.html

I wouldn't bother with the API unless I was writing GUI applications
that needed a C++ library to link against; the most I'd do is write
in Python (which I like a lot) and use the "p4 -G" option to have it
write its output (and read its input) in Python-friendly "marshal"
objects.

-jab

[Chris Patti]

At 04:32 PM 10/30/2001 -0800, you wrote:
>[Sending a copy to perforce-user, since I think that these URLs are
>particularly useful. And "yes, the command-line interface is so
>robust and easy to use that I would NOT bother with the C++ API
>for any sort of build needs, ever. For linking against an application
>written in C++ that does other stuff, maybe; for Perl/shell/Python
>sorts of scripts, the command-line's great!" -jab]
>
>At 12:32 PM 10/30/2001 -0700, you wrote:
>>Thanks for your response Jeff--I'll look into it. Do you know if the
>>command-line interface is very robust?
>
> VERY robust. You'll find FAQs at
> http://public.perforce.com/public/perforce/faq/index.html
> The build one is
> http://public.perforce.com/public/perforce/faq/build.html
>
> I wouldn't bother with the API unless I was writing GUI applications
> that needed a C++ library to link against; the most I'd do is write
> in Python (which I like a lot) and use the "p4 -G" option to have it
> write its output (and read its input) in Python-friendly
> "marshal" objects.
>
> -jab


Jeff;

All of what you say is completely true and I hope you'll understand that
I'm *NOT* arguing with any of it (In fact see my endorsement of your
suggestion below :)

However, doing the parsing by hand (even with -s, which is marginally
useful at best.. It considers a sync with no files needing to be synced an
error, whereas some REAL errors are marked info. Useless, or nearly so) is
not only a drag but a recipe for disaster.

A better solution is needed. Perforce's inclusion of the undocumented -G
option for Python scripters is proof positive that at least on some level
they're aware of this.

I agree that the C++ api approach is severely flawed as well for most
normal scripting applications - if faced with a choice between that
extremely complex, event driven API (Way, *WAY* too heavyweight for what
script writers want) and the command line flawed though it may be for
scripting purposes, I'll choose the command line any day of the week.

If I can find time I plan to pursue a solution for Java that uses a Java
class someone wrote that understands the Python marshalled object format,
thus making Java a usable vehicle for pre-parsed objects to be passed back
from the p4 client using the -G option, more detail to follow.

-Chris
(The Java class in question is at
http://www.gjt.org/pkgdoc/org/gjt/jjt/marshal/index.html )

[Chris Patti]

At 10:03 PM 10/31/2001 -0800, you wrote:
>At 06:02 PM 10/31/2001 -0500, Chris Patti wrote:
> >Jeff;
> >
> >All of what you say is completely true and I hope you'll understand that
> I'm *NOT* arguing with any of it (In fact see my endorsement of your
> suggestion below :)
> >
> >However, doing the parsing by hand (even with -s, which is marginally
> useful at best.. It considers a sync with no files needing to be synced
> an error, whereas some REAL errors are marked info. Useless, or nearly
> so) is not only a drag but a recipe for disaster.
>
>What you need to be able to script from a command line interface are
>consistency
>and completeness. If you know the utility well enough to wrap it up you
>know how
>to account for the times when its output is arcane.

[Chris Patti]

At 04:17 PM 11/1/2001 +0000, you wrote:
>On Thursday 01 November 2001 15:34, Chris Patti wrote:
>
> > My issue is that given the nature of the transactions being enacted between
> > client and server, it's a very reasonable thing to want a concise,
> > impossible to mis-parse *return code* for each Perforce operation that's
> > performed, the -G interface does this, and that's IMO the only way to go
> > for critical applications - stdout can be mis-interpreted, extraneous
> > output can be fed into the loop, edge cases are MUCH harder to code for,
> > the list goes on. (I can hear some folks shaking their heads. Examine if
> > you will the case of needing to write a bootstrapping script, which pulls
> > down an image to get someone started from the Perforce server with minimal
> > setup. Many things can go wrong, the script wants to do a 'p4 print' of
> > the bootstrap file on to the client's HD. How does one separate the output
> > from the return status using the -s option?)
>
>Hi Chris,
>
>Java I can't help you with, but would a Ruby extension with support for error
>detection via Exceptions meet your needs? I know we discussed this a while
>ago, but I've finally gotten around to doing something about it. I think it
>(and in fact my Perl API too) addresses most of your concerns.
>
>The first cut should be checked into the public depot today though I daresay
>it'll be a while before the interface is stable. It'll be in
>
>//guest/tony_smith/perforce/API/Ruby/...
>
>Other features:
>
>* Response to all commands is an array
>* In "tagged" output, the array contains hashes
>* In non-tagged output, the array contains strings.
>* Can parse Perforce forms into Ruby hashes. You can modify these hashes and
>supply them as input. (e.g. "p4 change -o" -> Ruby hash -> "p4 submit -i"
>much the same as you can do using my Perl extension )
>
>Sample code:
>
>require "P4"
>
>p4 = P4.new()
>p4.port( "localhost:1666" )
>p4.tagged()
>p4.connect()
>begin
> users = p4.run( "users" )
> users.each do
> |u|
> u.each do
> |key,val|
> puts( "#{key}\t=> #{val}" )
> end
> puts( "" )
> end
>rescue P4Exception => err
> puts( err )
>end
>
>Produces:
>
>User => administrator
>Email => ***@oolong-nt
>Access => 884204896
>FullName => administrator
>Update => 847922370
>
>User => baron
>Email => ***@cinnamon
>Access => 1004606632
>FullName => baron
>Update => 870136129
>
>etc. etc.
>
>It's still quite raw, so any feedback would be appreciated. I'll be
>submitting it in the next hour or so.
>
>Regards,
>
>Tony

Tony - This is _sweet_ but unfortunately my company is a Java shop and so
the Ruby integration is awesome for my personal scripts but for anything
official I don't think it'll fly (We're currently in severe time crunch
mode and adding another language to the mix would be a severe mistake at
this point, much as I adore Ruby)

I'll take a look thanks for all your hard work! (The exception approach is
just dandy, BTW :)

-Chris

[Gordon Broom]

Also be aware that "p4 -s" may not handle "text:" lines properly
(job005070). It certainly did it in P4D/NTX86/2000.2/19882, and I assume
it's in 2001.1 too. I haven't received a notification on this bug, and have
used "p4 -G" to work around it (and also haven't upgraded to 2001.1 yet
(shhh.... :-) ). Both "p4 -s" and "p4 -G" return the output from the
underlying ,v file in 4096 byte chunks. The "p4 -s" output splits a text
line that straddles a 4K boundary into 2 "text:" lines, so upon reassembly
you have spurious newlines (because normally the newline in the data also
terminates the "text:" tag). Even though "p4 -G" returns the data in 4K
chunks too, you don't have a problem because all the meta data is "out of
band".

Gordon Broom
Configuration Management Engineer
Power Measurement Ltd. <http://www.pwrm.com/>
[phone] x7608


-----Original Message-----
From: Chris Patti [mailto:***@atg.com]
Sent: Wednesday, October 31, 2001 3:02 PM
To: perforce-***@perforce.com
Subject: RE: [p4] Java interface to Perforce / P4API for Java


At 04:32 PM 10/30/2001 -0800, you wrote:
>[Sending a copy to perforce-user, since I think that these URLs are
>particularly useful. And "yes, the command-line interface is so
>robust and easy to use that I would NOT bother with the C++ API
>for any sort of build needs, ever. For linking against an application
>written in C++ that does other stuff, maybe; for Perl/shell/Python
>sorts of scripts, the command-line's great!" -jab]
>
>At 12:32 PM 10/30/2001 -0700, you wrote:
>>Thanks for your response Jeff--I'll look into it. Do you know if the
>>command-line interface is very robust?
>
> VERY robust. You'll find FAQs at
> http://public.perforce.com/public/perforce/faq/index.html
> The build one is
> http://public.perforce.com/public/perforce/faq/build.html
>
> I wouldn't bother with the API unless I was writing GUI
applications
> that needed a C++ library to link against; the most I'd do is
write
> in Python (which I like a lot) and use the "p4 -G" option to have
it
> write its output (and read its input) in Python-friendly
> "marshal" objects.
>
> -jab


Jeff;

All of what you say is completely true and I hope you'll understand that
I'm *NOT* arguing with any of it (In fact see my endorsement of your
suggestion below :)

However, doing the parsing by hand (even with -s, which is marginally
useful at best.. It considers a sync with no files needing to be synced an
error, whereas some REAL errors are marked info. Useless, or nearly so) is
not only a drag but a recipe for disaster.

A better solution is needed. Perforce's inclusion of the undocumented -G
option for Python scripters is proof positive that at least on some level
they're aware of this.

I agree that the C++ api approach is severely flawed as well for most
normal scripting applications - if faced with a choice between that
extremely complex, event driven API (Way, *WAY* too heavyweight for what
script writers want) and the command line flawed though it may be for
scripting purposes, I'll choose the command line any day of the week.

If I can find time I plan to pursue a solution for Java that uses a Java
class someone wrote that understands the Python marshalled object format,
thus making Java a usable vehicle for pre-parsed objects to be passed back
from the p4 client using the -G option, more detail to follow.

-Chris
(The Java class in question is at
http://www.gjt.org/pkgdoc/org/gjt/jjt/marshal/index.html )


_______________________________________________
perforce-user mailing list - perforce-***@perforce.com
http://maillist.perforce.com/mailman/listinfo/perforce-user

[Chuck Karish]

At 06:02 PM 10/31/2001 -0500, Chris Patti wrote:
>Jeff;
>
>All of what you say is completely true and I hope you'll understand that I'm *NOT* arguing with any of it (In fact see my endorsement of your suggestion below :)
>
>However, doing the parsing by hand (even with -s, which is marginally useful at best.. It considers a sync with no files needing to be synced an error, whereas some REAL errors are marked info. Useless, or nearly so) is not only a drag but a recipe for disaster.

What you need to be able to script from a command line interface are consistency
and completeness. If you know the utility well enough to wrap it up you know how
to account for the times when its output is arcane.

>A better solution is needed. Perforce's inclusion of the undocumented -G option for Python scripters is proof positive that at least on some level they're aware of this.

It's not undocumented any more ...

>I agree that the C++ api approach is severely flawed as well for most normal scripting applications - if faced with a choice between that extremely complex, event driven API (Way, *WAY* too heavyweight for what script writers want) and the command line flawed though it may be for scripting purposes, I'll choose the command line any day of the week.

Me, too.


Chuck Karish ***@well.com [phone]

[Gregg G. Wonderly]

>

[Hoff, Todd]

> Your thoughts are right on though. Perforce needs a 100% java API
> implementation of the library that will allow easy and
> concise applications to
> be written, and have them be dependable and robust.

Better to be language neutral and use XML-RPC and/or SOAP.

[Rick Macdonald]

As the author of "TkP4" (http://web.cuug.ab.ca/~macdonal/tkp4) I can agree
that parsing p4 stdout/stderr is a pain because of some inconsistencies
and other issues. A year ago Perforce (Chris himself) had offered
(tentitively) to add a switch for me (that would be similar to the python
-G) to output Tcl format for me, but that never happened.

As for the failed Java client, as I recall they tried to use JNI so they
probably don't have a pure Java API library laying around.

At the conference a year ago I stated in my TkP4 presentation that, as
much as I enjoy developing TkP4, I think the company really should provide
a proper multiplatform client.

That said, I'm sure we customers will still want a multiple-platform API
to roll our own, and people will always write simple scripts to parse p4
command output.

On Mon, 5 Nov 2001, Gregg G. Wonderly wrote:

> >