 Bob Balaban | Bob Balaban January 2 2012 03:56:33 AMHappy New Year, Geeks! Here's the 7th (and final) installment of the book. Thanks again for all the positive feedback. The first installment can be found here The 2nd installment is here The 3rd is here The 4th is here The 5th is here and the 6th is here All of the book content (as is all of the content on this blog) is Copyright 1998 and 2011 by Looseleaf Software, Inc. You may not reproduce or distribute the book's content without permission from me.
Some Caveats and explanations: - This book is now 12 years old. There are lots of things in it that are amusingly dated, even laughable. One example: the absurd emphasis on Java Applets. They died an unlamented death due to bloating a long time ago, but at the time I wrote the book, they were a hot technology. - The formatting is not exactly as it first appeared in the book, and some of it is downright awkward. Sorry! The publisher converted the original files to Word for me, perhaps they forgot to select the "high-def" option. - The Java package described in the book (lotus.notes) was superseded by lotus.domino in R5 (1999? I think). The methods are all mostly the same. Of course, IBM have added lots more classes and methods than existed when the book was written. Also, the "recycle()" method had not yet been invented in Domino 4.6, so the memory issues that call addresses are not really covered. - The figures (screen shots and so on) referred to did not make it into any file format I can deal with, so I had to leave them out. Sorry! The code samples are mostly there, and I'll also post all of the files that were on the CD that came with the original book.
This Installment This hunk is a zip file containing the contents of the CD that was included with the original book. Appendix F (previously posted) contains a description of the contents of the CD: Appendix F.pdf I have not gone back and checked that the samples still work. If you find that any do not, please let me know. The JavaDoc, of course, corresponds to the Notes v4.0 release. "NOI" has come a long way since then, and the whole lotus.notes package was pretty much obsoleted in Notes v5, but they may still be distributing it. CD.zip Enjoy! Geek ya later (Need expert application development architecture/coding help? Want me to help you invent directory services based on RDBMS? Need some Cloud-fu or some web services? Contact me at: bbalaban, gmail.com)
Follow me on Twitter @LooseleafLLC
This article ©Copyright 2010 by Looseleaf Software LLC, all rights reserved. You may link to this page, but may not copy without prior approval.
Bob Balaban December 6 2011 11:17:56 AMGreetings, Geeks! Here's the 6th installment of the book. Thanks again for all the positive feedback. The first installment can be found here The 2nd installment is here The 3rd is here The 4th is here The 5th is here All of the book content (as is all of the content on this blog) is Copyright 1998 and 2011 by Looseleaf Software, Inc. You may not reproduce or distribute the book's content without permission from me.
Some Caveats and explanations: - This book is now 12 years old. There are lots of things in it that are amusingly dated, even laughable. One example: the absurd emphasis on Java Applets. They died an unlamented death due to bloating a long time ago, but at the time I wrote the book, they were a hot technology. - The formatting is not exactly as it first appeared in the book, and some of it is downright awkward. Sorry! The publisher converted the original files to Word for me, perhaps they forgot to select the "high-def" option. - The Java package described in the book (lotus.notes) was superseded by lotus.domino in R5 (1999? I think). The methods are all mostly the same. Of course, IBM have added lots more classes and methods than existed when the book was written. Also, the "recycle()" method had not yet been invented in Domino 4.6, so the memory issues that call addresses are not really covered. - The figures (screen shots and so on) referred to did not make it into any file format I can deal with, so I had to leave them out. Sorry! The code samples are mostly there, and I'll also post all of the files that were on the CD that came with the original book.
This Installment We're done with the main body of text (Chapters 1-14), but there's still more good stuff to post: Appendix A "Useful Links and References" Appendix A.pdf Appendix B "Notes Object Interface Class Diagram" (yeah, a little out of date now...) Appendix B.pdf Appendix C "Domino Setup For Writing Java Programs" Appendix C.pdf Appendix D "Notes Object Interface Exceptions" Appendix D.pdf Appendix E "Creating LSXs" (Note: This was WAY before Lotus released the "LSX Toolkit", known far and wide in song and legend. You can probably still get the toolkit at this site, though I haven't checked lately. It hasn't had a new release in years, and is known to be broken for recent versions of Microsoft Visual Studio) Appendix E.pdf Appendix F "What's On the CD-ROM" Appendix F.pdf Next installment, I'll post the samples and javadoc from the CD Enjoy! Geek ya later (Need expert application development architecture/coding help? Want me to help you invent directory services based on RDBMS? Need some Cloud-fu or some web services? Contact me at: bbalaban, gmail.com)
Follow me on Twitter @LooseleafLLC
This article ©Copyright 2010 by Looseleaf Software LLC, all rights reserved. You may link to this page, but may not copy without prior approval.
Bob Balaban November 28 2011 05:22:21 PMGreetings, Geeks! Here's the 5th installment of the book. Thanks again for all the positive feedback. The first installment can be found here The 2nd installment is here The 3rd is here The 4th is here All of the book content (as is all of the content on this blog) is Copyright 1998 and 2011 by Looseleaf Software, Inc. You may not reproduce or distribute the book's content without permission from me.
Some Caveats and explanations: - This book is now 12 years old. There are lots of things in it that are amusingly dated, even laughable. One example: the absurd emphasis on Java Applets. They died an unlamented death due to bloating a long time ago, but at the time I wrote the book, they were a hot technology. - The formatting is not exactly as it first appeared in the book, and some of it is downright awkward. Sorry! The publisher converted the original files to Word for me, perhaps they forgot to select the "high-def" option. - The Java package described in the book (lotus.notes) was superseded by lotus.domino in R5 (1999? I think). The methods are all mostly the same. Of course, IBM have added lots more classes and methods than existed when the book was written. Also, the "recycle()" method had not yet been invented in Domino 4.6, so the memory issues that call addresses are not really covered. - The figures (screen shots and so on) referred to did not make it into any file format I can deal with, so I had to leave them out. Sorry! The code samples are mostly there, and I'll also post all of the files that were on the CD that came with the original book.
This Installment This time I'm posting 3 more chapters: Chapter 12: "NOI and Java Beans" (Are they really good for your heart?) Chapter 12.pdf Chapter 13: "JDBC and NOI" Chapter 13.pdf Chapter 14: A Look Ahead to Domino 5 (This ought to provide some laughs, eh?) Chapter 14.pdf Note: Chapter 14 is the last real chapter, but there's still plenty more to come. To wit: - Appendices A through F - Samples, including some javadoc, since I happen to have it anyway
Release Notes Chapter 12: No bugs! Chapter 13: No bugs! Chapter 14: Also bug-free! Enjoy! More soon. Geek ya later Bob Balaban November 20 2011 01:30:47 PMGreetings, Geeks! Here's the 4th installment of the book. Thanks again for all the positive feedback. The first installment can be found here The 2nd installment is here The 3rd is here All of the book content (as is all of the content on this blog) is Copyright 1998 and 2011 by Looseleaf Software, Inc. You may not reproduce or distribute the book's content without permission from me.
Some Caveats and explanations: - This book is now 12 years old. There are lots of things in it that are amusingly dated, even laughable. One example: the absurd emphasis on Java Applets. They died an unlamented death due to bloating a long time ago, but at the time I wrote the book, they were a hot technology. - The formatting is not exactly as it first appeared in the book, and some of it is downright awkward. Sorry! The publisher converted the original files to Word for me, perhaps they forgot to select the "high-def" option. - The Java package described in the book (lotus.notes) was superseded by lotus.domino in R5 (1999? I think). The methods are all mostly the same. Of course, IBM have added lots more classes and methods than existed when the book was written. Also, the "recycle()" method had not yet been invented in Domino 4.6, so the memory issues that call addresses are not really covered. - The figures (screen shots and so on) referred to did not make it into any file format I can deal with, so I had to leave them out. Sorry! The code samples are mostly there, and I'll also post all of the files that were on the CD that came with the original book.
This Installment This time I'm posting 3 more chapters: Chapter 9 (Debugging NOI Agents) - Chapter 09.pdf NOTE: When I wrote the book, Eclipse was not yet invented (or at least, widely known). I hadn't yet come up with the now-common "2-Headed Beast" technique of debugging Java agents (Why hasn't IBM created a way to debug agents inside Designer in the 14 years that Java agents have been loose in the world? I don't know, but it's sad). See here for a description of "2-Headed Beast". Chapter 10 (Sharing Objects Across Threads) - Chapter 10.pdf Chapter 11 (Upgrading Servlets to Agents) - Chapter 11.pdf Release Notes Chapter 9: No bugs! Chapter 10: No bugs! Chapter 11: No bugs! Enjoy! More soon. Geek ya later Bob Balaban November 14 2011 06:28:59 PMGreetings, Geeks! Here's the third installment of the book. Thanks again for all the positive feedback. The first installment can be found here The 2nd installment is here All of the book content (as is all of the content on this blog) is Copyright 1998 and 2011 by Looseleaf Software, Inc. You may not reproduce or distribute the book's content without permission from me.
Some Caveats and explanations: - This book is now 12 years old. There are lots of things in it that are amusingly dated, even laughable. One example: the absurd emphasis on Java Applets. They died an unlamented death due to bloating a long time ago, but at the time I wrote the book, they were a hot technology. - The formatting is not exactly as it first appeared in the book, and some of it is downright awkward. Sorry! The publisher converted the original files to Word for me, perhaps they forgot to select the "high-def" option. - The Java package described in the book (lotus.notes) was superseded by lotus.domino in R5 (1999? I think). The methods are all mostly the same. Of course, IBM have added lots more classes and methods than existed when the book was written. Also, the "recycle()" method had not yet been invented in Domino 4.6, so the memory issues that call addresses are not really covered. - The figures (screen shots and so on) referred to did not make it into any file format I can deal with, so I had to leave them out. Sorry! The code samples are mostly there, and I'll also post all of the files that were on the CD that came with the original book.
This Installment I'm including 3 chapters in this post: Chapter 6 (NOI Part 5): Chapter 06.pdf Chapter 7 (Writing NOI Applications): Chapter 07.pdf Chapter 8 (Writing NOI Agents): Chapter 08.pdf
Release Notes Chapter 6, Page 195. Description of Registration.addUserProfile() mistakenly refers to Database.createProfileDocument(). Should be setProfileDocument() Chapter 7, no bugs! Chapter 8, Page 265. Listing 8.3 ("Waiting for Child Threads, Ex83Multi.java). Sigh. This code has a major race condition in it that I didn't catch until after the book was out. Basically, the problem is that all of the threads could finish before you get to the logic that tests to see if any of them are alive. There's a better and much more robust pattern for doing this stuff that I could write a separate article about, if there's interest. Enjoy! More soon. Geek ya later Bob Balaban November 9 2011 04:28:19 PMGreetings, Geeks! Here's the second installment of the book. Thanks again for all the positive feedback. The first installment can be found here All of the book content (as is all of the content on this blog) is Copyright 1998 and 2011 by Looseleaf Software, Inc. You may not reproduce or distribute the book's content without permission from me.
Some Caveats and explanations: - This book is now 12 years old. There are lots of things in it that are amusingly dated, even laughable. One example: the absurd emphasis on Java Applets. They died an unlamented death due to bloating a long time ago, but at the time I wrote the book, they were a hot technology. - The formatting is not exactly as it first appeared in the book, and some of it is downright awkward. Sorry! The publisher converted the original files to Word for me, perhaps they forgot to select the "high-def" option. - The Java package described in the book (lotus.notes) was superseded by lotus.domino in R5 (1999? I think). The methods are all mostly the same. Of course, IBM have added lots more classes and methods than existed when the book was written. Also, the "recycle()" method had not yet been invented in Domino 4.6, so the memory issues that call addresses are not really covered. - The figures (screen shots and so on) referred to did not make it into any file format I can deal with, so I had to leave them out. Sorry! The code samples are mostly there, and I'll also post all of the files that were on the CD that came with the original book.
This Installment I'm including 3 chapters in this post: Chapter 3 (NOI Part 2) -- was supposed to be in the previous posting, but ooops. Sorry: Chapter 03.pdf Chapter 4 (NOI Part 3): Chapter 04.pdf Chapter 5 ( Yes! You guessed it...NOI Part 4): Chapter 05.pdf Don't worry, the chapter titles get a little more inventive starting with Chapter 7.
Release Notes Chapter 3: Page 98, All of the "Item.appendXXX" method names should have capitalized "Value" Page 113, discussion of "auto-update", it describes how you can use getNextDocument(), etc. "That'll work okay". It won't work ok, it'll potentially cause an infinite loop. Ooops. Page 117, Listing 3.6, the "for" loop starts an index at 0, should be 1. Same for the loop on Page 118 as well. Page 119, mentions a property on View named "IsHierarchical". There is no such property (or at least, there wasn't in 4.6) Chapter 4: No bugs! Chapter 5: No bugs! Enjoy! More soon. Geek ya later Bob Balaban November 2 2011 05:50:15 PMGreetings, Geeks! Here's the first installment of the book. Thanks again for all the positive feedback. All of the book content (as is all of the content on this blog) is Copyright 1998 and 2011 by Looseleaf Software, Inc. You may not reproduce or distribute the book's content without permission from me. Some Caveats and explanations: - This book is now 12 years old. There are lots of things in it that are amusingly dated, even laughable. One example: the absurd emphasis on Java Applets. They died an unlamented death due to bloating a long time ago, but at the time I wrote the book, they were a hot technology. - The formatting is not exactly as it first appeared in the book, and some of it is downright awkward. Sorry! The publisher converted the original files to Word for me, perhaps they forgot to select the "high-def" option. - The Java package described in the book (lotus.notes) was superseded by lotus.domino in R5 (1999? I think). The methods are all mostly the same. Of course, IBM have added lots more classes and methods than existed when the book was written. Also, the "recycle()" method had not yet been invented in Domino 4.6, so the memory issues that call addresses are not really covered. - The figures (screen shots and so on) referred to did not make it into any file format I can deal with, so I had to leave them out. Sorry! The code samples are mostly there, and I'll also post all of the files that were on the CD that came with the original book. This Installment I'm including the Dedication/Preface, and Chapters 1 ("Programmability Overview"), 2 ("NOI Part 1") and 3 ("NOI Part 2"). "NOI" is "Notes Object Interface", what we called the "back-end classes" in the day. Preface/etc.: ded_ack_pref.pdf Chapter 1: Chapter 01.pdf Chapter 2: Chapter 02.pdf Release Notes Chapter 2: Page 15, "Refer to Appendix A for a diagram...", should be "Appendix B" Page 33, Listing 2.2, Missing closing curly-brace "}" right before the "catch" statement Page 58, description of Database.createCopy() method, should mention that the method does not copy data, only the design of the db Chapter 3: Page 98, All of the "Item.appendXXX" method names should have capitalized "Value" Page 113, discussion of "auto-update", it describes how you can use getNextDocument(), etc. "That'll work okay". It won't work ok, it'll potentially cause an infinite loop. Ooops. Page 117, Listing 3.6, the "for" loop starts an index at 0, should be 1. Same for the loop on Page 118 as well. Page 119, mentions a property on View named "IsHierarchical". There is no such property (or at least, there wasn't in 4.6) Enjoy! More soon. Bob Balaban October 29 2011 09:34:15 AMGreetings, Geeks! In 1998 I published a book titled "Programming Domino 4.6 With Java" (see the Amazon page here). It did fairly well, but of course it's a bit dated now, and it went out of print in 2000. While you can apparently get a used copy for $0.59 (plus shipping), I was thinking I might post the PDF version of the whole thing here on my blog (the rights to the book reverted to me when the publisher declared it out of print, so it's legal). There are bugs in there, which I suppose I could publish "release notes" for, too. I think it's still the best detailed description of the Java "back-end classes" for N/D, as that library existed in October, 1997. Any interest? If you'd like to see it, post a comment here. If you wouldn't like to see it, post a comment here. Geek ya later! Bob Balaban April 4 2011 05:45:00 AMGreetings, Geeks! Recently I posted some sample code showing you how to convert Notes documents to MIME format on disk, using the Notes Java APIs. Unfortunately, if you need to do this kind of conversion using some other platform (such as .net), the job is a bit harder. A key method on the Document class (doc.convertToMIME()) is missing in the COM classes for Notes. Why? No idea, someone should ask Lotus about that. Probably has something to do with fear (but that's just speculation on my part). No worries, though. the convertToMIME() method uses public C API calls to do its work, so we can do the same from a .net program. For starters, see my blog post on calling C API from C# (c-sharp) programs, here. That post talks about the basic techniques and syntax for setting up any kind of call-out from C# to C, so I won't repeat that here (the idea is just about the same if you're using vb). Here's a c-sharp file that provides a bunch of wrappers for Notes C API calls, bundled together in a class called NotesEntriess. NotesEntries.cs The tedious bit about doing MIME conversion for a .net program is that there are several C calls you have to make for the 1 Java/LotusScript call. The tricky part is that, to do it without having to do everything at the C API level, you want to save typing by leveraging the COM classes, and only use the NotesEntries wrappers when you have to. The problem is that the COM classes do not expose the in-memory "handle" for a NotesDocument instance -- you can only get the Note ID -- while the C API calls require the handle for most things. So you'll see in the sample program "BlogMIME.cs" ( BlogMIME.cs) that the first part of the work (converting a document to MIME format in memory) is done with C API wrappers (after using "regular" COM classes to access the NSF and find the document in the first place, of course). I could have continued to use the C API to iterate over MIMEParts in the converted document, force Base64 encoding, and write out the results, but it's really much easier to do all that using COM classes. Unfortunately, there's no way to take the NOTEHANDLE that I get using the C API and use it to get a NotesDocument COM object. I had to save() the document back to disk, get the Note ID, and use that to "get" the document again via COM. There's a slight performance hit for the extra save, but it was worth it in this case. You'll notice that the c# code that actually writes out the converted MIME document to disk is almost a line-for-line translation of the Java code I posted earlier. That's possible because the Notes COM classes are almost identical (on purpose) to the Java and LotusScript interfaces. The only reason we have to get tricky with using C API wrappers is that the Document.convertToMIME() function is missing in the COM interface. There are some other nice (reusable) features of the c# code, such as mapping various C constants to c# syntax, and so on. So, take the code, use it as a source of techniques for doing this kind of integration. Enjoy! Geek ya later. (Need expert application development architecture/coding help? Want me to help you invent directory services based on RDBMS? Need some Cloud-fu or some web services? Contact me at: bbalaban, gmail.com)
Follow me on Twitter @LooseleafLLC
This article ©Copyright 2010 by Looseleaf Software LLC, all rights reserved. You may link to this page, but may not copy without prior approval.
Bob Balaban March 21 2011 04:00:00 AMGreetings, Geeks!
MIME is a data format that has become central to transmission of email over the Internet. The nice thing about it is that everyone uses it for mail interchange, and that it's standard. The Domino server converts incoming MIME-formatted messages into Notes documents, and outgoing Notes email documents into MIME formats. As of (I think) Notes v6, you can specify that you want incoming MIME messages to remain in their native format within the NSF database. In these cases, the Notes client will automatically convert any document that resides in MIME format to "regular" Notes rich text document format when you open it in the client UI. What does MIME format look like? It can get complicated, but the easiest way to think of it is as a sectioned box, with each compartment within the box holding data in a specified format. So, plain text is just a plain-text section. "Rich text" is usually represented as HTML, with embedded "pointers" to other sections containing embedded objects, such as images or attachments. Other data, such as file attachments, reside in their own sections, with their own "headers" specifying size, encoding (e.g., base-64) and format (e.g., JPEG or GIF). The different sections in the MIME file are separated by "boundaries", essentially a unique string. There's much more to it, of course, but these are the basics. What if you want to write script (LotusScript, Java, other) to programmatically convert Notes documents to MIME format? If you're using a recent (v8.5x) version of Notes or Domino, then most of the work is done for you with new methods in the back-end classes. This functionality is, of course, based on entry points in the Notes C API. If you're not using LotusScript or Java, you can accomplish MIME translation with a C or C++ program using these entry points, or, even easier, use the COM classses. I'll discuss how to do MIME conversion using the C and COM APIs in Part Deux of this post. Here's a basic Java program showing the essential techniques for conversion. I'm leaving out all the surrounding code for acquiring Document objects, preparing FileOutputStreams, and so on. There is only one slightly tricky thing about this program, which we'll get to after this first section. Session session = NotesFactory. createSession(); // turn off automatic mime conversion on document open // if doc is already in MIME, leave it so session.setConvertMIME( false); Document doc = .... // get document somewhere // kill any $KeepPrivate items doc.removeItem("$KeepPrivate"); doc.convertToMIME(lotus.domino.Document. CVT_RT_TO_HTML, 0); // note: Designer doc has wrong spelling WriteOutputMIME(doc); So far, so good. We suppress automatic conversion on document open, to save work (if the document is already in MIME format, we can skip the convert step and just write it out). If the "$KeepPrivate" item is present in the document, conversion will fail, so we remove that. Then all we do is call the Document.convertToMIME() method, specifying that we want rich text converted to HTML. After the convert call, the document in memory is now a sequence of items containing MIME headers, and a (possibly multi-part) body representing the rich text body of the original document, plus any attachments it contains. We can (almost) proceed to iterate over these items and write them out to disk (or wherever). I say "almost", though, because there's a glitch in the conversion code deep underneath the C API layer: it does not automatically convert attachment contents to a base-64 encoding (even though the API documentation says it will) - it leaves them in binary format, which cannot be written to disk. So, we have to look for those items, and force them to be converted to base-64 text. This next section of Java code for the WriteOutputMIME() functions shows how to do that. Again, I've pared the code down to the essential bits: private void WriteOutputMIME(Document doc, File outDir) throws Exception { File outFile = null; MIMEEntity mE = null; MIMEEntity mChild = null; String contenttype = null; String headers = null; String content = null; String preamble = null; int encoding; FileWriter output = null; String noteid = doc.getNoteID(); int index; // access document as mime parts mE = doc.getMIMEEntity("Body"); outFile = new File(outDir, noteid + ".eml"); output = new FileWriter(outFile); try { contenttype = mE.getContentType(); headers = mE.getHeaders(); encoding = mE.getEncoding(); // message envelope. If no MIME-version header, add one index = headers.indexOf("MIME-Version:"); if (index < 0) output.write("MIME-Version: 1.0\n"); output.write(headers); // for multipart, usually no main- msg content content = mE.getContentAsText(); if (content != null && content.trim().length() > 0) { output.write(content); output.write("\n"); } // For multipart, examine each child entity, // re-code to base64 if necessary if (contenttype.startsWith("multipart")) { preamble = mE.getPreamble(); mChild = mE.getFirstChildEntity(); while (mChild != null) { headers = mChild.getHeaders(); encoding = mChild.getEncoding(); // convert binary parts to base-64 if (encoding == MIMEEntity. ENC_IDENTITY_BINARY) { mChild.encodeContent(MIMEEntity. ENC_BASE64); headers = mChild.getHeaders(); // get again, because changed } preamble = mChild.getPreamble(); content = mChild.getBoundaryStart(); output.write(content); if (!content.endsWith("\n")) output.write("\n"); output.write(headers); output.write("\n"); content = mChild.getContentAsText(); if (content != null && content.length() > 0) output.write(content); output.write(mChild.getBoundaryEnd()); mChild = mChild.getNextSibling(); } // end while } // end multipart // end of main envelope output.write(mE.getBoundaryEnd()); } finally { if (output != null) output.close(); } } // end WriteOutptuMIME So, a little tricky, but not too bad. You have to get the boundaries right, as well as the line breaks. Otherwise, it's really just copying stuff out to disk. Remember that the message has some overall headers (mE.getHeaders()), and each child entity has its own header section as well, describing what's in that chunk of data. When we re-code an entity from binary format to base-64 format, we need to re-read the entity headers, because they'll reflect that change. A final comment about HTML conversion: it theoretically existed back in R5 (you know what they say about "in theory"...), but it didn't start working well for real until v7.03. And it has been improving ever since, so the later the version of the product you have, the better off you'll be. In my next blog post (part deux), I'll show you how to adapt this basic code for the Notes COM classes, where (for some stupid reason) the Document.convertToMIME() function does not exist). We will not be thwarted! I'll show you how to use the Notes C API from a C-sharp program to do the MIME conversion. Happy coding! Geek ya later! (Need expert application development architecture/coding help? Want me to help you invent directory services based on RDBMS? Need some Cloud-fu or some web services? Contact me at: bbalaban, gmail.com)
Follow me on Twitter @LooseleafLLC
This article ©Copyright 2010 by Looseleaf Software LLC, all rights reserved. You may link to this page, but may not copy without prior approval.
Bob Balaban March 14 2011 02:15:00 AMGreetings, Geeks! If you're writing Domino Java agents that use HTTP requests to talk to the Internets, you might need to debug your code by capturing the actual bits that leave your computer as Web requests, or even by looking at the responses that come back. I recently had to do just that for a customer project. I could write debug logs for the URLs and "payloads" that I was sending and receiving, but you don't easily get to see the HTTP headers that come and go. I found that I could download and configure Fiddler (it's free here) to reveal all, for both "normal" HTTP and also for HTTPS connections. First of all, if you're debugging Java agents for Notes or Domino, I hope you're doing it in Eclipse, as described in my "2-Headed Beast" posting. There's only 1 little trick you need to know to make it work properly. Because Fiddler acts as a "proxy", inserting itself between your program and your network you have to tell Java to send HTTP commands to Fiddler, instead of directly to your network adapter (other programs, like the Chrome client for GMail automatically look for proxies, and require no special configuration). The way you tell Eclipse to do what you want is to go to the "Run Configuration" (or "Debug Configuration") dialog, click on the "Arguments" tab, and enter these JVM arguments into the "VM arguments" box: -DproxySet=true -DproxyHost=127.0.0.1 -DproxyPort=8888 Click "Apply", and you're all set. Launch Fiddler before you run/debug your code, and it will capture all the HTTP traffic out and in. Click the "Raw" button in Fiddler to see everything (outgoing in the top pane, incoming in the bottom pane), including headers. Voilà! It's especially fun to use with Web Services. What about doing this in Domino Designer? I haven't found an equivalent setting that allows me to specify the extra JVM arguments that Fiddler needs. It may be that if you can tweak the Run Configuration for your agents in Designer (see my blog post on how to do that), you can get it to work - I haven't tried it. What about LotusScript? Well, unfortunately, LotusScript has never had native HTTP capabilities (probably never will). Most people who want to use HTTP from a LotusScript program use outside libraries that you can invoke using DECLARE statements, or (on Windows systems), use the COM interfaces to libraries such as MSXML. Well, there you have it. Happy coding! Geek ya later! (Need expert application development architecture/coding help? Want me to help you invent directory services based on RDBMS? Need some Cloud-fu or some web services? Contact me at: bbalaban, gmail.com)
Follow me on Twitter @LooseleafLLC
This article ©Copyright 2010 by Looseleaf Software LLC, all rights reserved. You may link to this page, but may not copy without prior approval.
Bob Balaban February 28 2011 11:15:14 AMGreetings, Geeks! I read with concern the recent reports of some GMail accounts disappearing, as I use a couple of them for business and other purposes. I thought about writing a program to download all my mail and store as backup in a Notes database, but then I remembered that Notes already has a built-in feature for doing that: IMAP integration. It took me 5 minutes to set it up and download over 7000 messages from my (thankfully still operating) GMail account. It even converted GMail "labels" into NSF folders. So, here's how you do it (I used Notes 8.52, I think it works in v7 as well): 1) Go to your local Contacts database (ooops, I mean "Application"!), names.nsf 2) Click on "Advanced" in the navigator, then "Accounts" 3) Create a new Account document 4) Name it anything ("gmail") 5) "Account server" is "imap.gmail.com" (don't enter the quotes) 6) Login is your GMail account name, including the @gmail.com part 7) For Protocol I used "IMAP online". I didn't experiment with the "IMAP offline" feature, but I suspect it adds your gmail mailbox to the replicator page for background sync. Maybe someone can confirm/deny 8) I changed the SSL setting to "Enabled", because I have my GMail account set up to use SSL So far so good, Notes creates a new NSF for IMAP sync. When you open it, Notes goes out to the IMAP account and synchronizes. First time I tried it, though I got an error "Invalid SSL certificates". I fixed that problem by going back into the Account document, and going to the "Advanced" tab. I changed the "Send SSL certificates when asked" option to "Yes". I also changed "Accept SSL site certs" to "Yes", though I don't know if that's required or not. Works great! Thanks Notes! Geek ya later (Need expert application development architecture/coding help? Want me to help you invent directory services based on RDBMS? Need some Cloud-fu or some web services? Contact me at: bbalaban, gmail.com)
Follow me on Twitter @LooseleafLLC
This article ©Copyright 2010 by Looseleaf Software LLC, all rights reserved. You may link to this page, but may not copy without prior approval.
Bob Balaban February 18 2011 03:25:00 PMGreetings, Geeks! This one is going to get uber-geeky real fast, so hang onto your gaming consoles. We need a little background, but I'll keep it brief. Most of you probably know that whenever a document is saved (written to disk in the NSF), 2 list items automatically get updated: $UpdatedBy is a list of the names of the people who modified (and, initially, created) the document. The $Revisions item is a list of date/time values indicating the times at which the updates occurred. So, these 2 lists are "parallel", in that the last name in $UpdatedBy can be assumed to have modified the document at the last date/time in $Revisions, and so on, back into history, as far as it goes. Somewhere back in the V4/V5 days, people started to notice that these lists could, over time, get pretty big. A new Distinguished Name (10-30 characters) plus a new date/time value (8 bytes) each time someone hits Ctl-S in a document can start to add up. Even small documents could end up bloated by "bookkeeping data". So someone invented two new properties in the Application (nee Database) Properties box, on the propeller-hat tab: "Limit Entries in $UpdatedBy fields" and "Limit Entries in $Revisions fields". By default, these settings have a value of zero, meaning (as usual), "no limit". But, should you desire, you can set these properties to non-zero values to keep the size of your documents from growing forever. Of course, it's nice if you set the 2 properties to the same value, to keep the 2 lists in "sync", but you're not forced to (is that recommendation even documented? I didn't check). Ok, so far so good. But, you ask, what does this have to do with replication? Aha! Well, first just a bit more background. Before Notes v4, there was only 1 replication granularity: full document. The replication logic matched up the documents in 2 NSF replicas by their UNIDs (Universal IDs). If one document's "last-modified" time is later than the others, then (keeping it simple here by skipping some gritty details) it "wins". That worked fine for quite a while, but it meant that the replicator had to copy the entire document from one NSF to another when one copy of the document had been modified, and the other hadn't. If the document contained 10mb of attachment data, well, tough, the replicator copied all 10 mb, because it had no way of knowing whether the attachment itself had been modified. Enter "Field Level Replication", somewhere in the V4 timeframe. (By the way, you may -- or may not -- be surprised to know that "replication" was never patented by Lotus or Iris. However, Field Level Replication was patented in the early 1990s). This is an optimization applied to the normal replication logic that allows for much greater efficiency, but it required a change to the on-disk representation (ODS) of documents. The key innovation in FLR was that a new C API entry point was created that could tell a caller (for example, the Replicator) the date/time of last modification of a single DATA ITEM in a given document. This new entry point allowed the replicator to enhance it's normal logic to say something like: "Ok, DocA and DocB are the same (same UNID). DocA has a later last-modified date. But I may not have to copy the WHOLE document to DocB's NSF. I can match up the pair-o'-docs item by item, and only update DocB with the items that are modified!" Clearly better when you've got a big replication with lots of changes. But, how does the item-last-modified API actually work? You certainly don't want to store a full 8 bytes of date/time data for each item in a document, that's an enourmous use of space. Instead, someone figured out that they could use only 3 or 4 bits to store an INDEX into the list of document last-modified dates for each item. My recollection is (I could be wrong about this) that the number is the count from the END of the $Revisions list. So, a "1" probably means "last entry in $Revisions", etc. Cool, huh? Clever! You get huge new functionality by spending only a few bits per data item. BUT! What if someone's set the db property to "Limit Entries in $Revision fields"?? What if (extreme case here) there are only 2 entries allowed, but items in some document have been modified 3 or 4 times in one replica, and not at all in another? Aye, there's the rub. The answer is, you lose field-level replication for that document, and any others like it. The "get me the item last-modified time" logic has to account for that, of course, and there's really only one thing it can reasonably do. If the last-mod "index" attached to an item is bigger than the length of the $Revisions list, it has to fall back to document last-modified time, because the last-modified time of the document is guaranteed to be greater than, or equal to, the last-modified time of any item in that document. So, there you have it: an unintended consequence of limiting the amount of $Revisions space used in a document is that you make replication run slower (in some situations). "Correctness" is not violated (important point!): you never lose data as a result. It's just that in some cases replication will take longer. How much longer? It depends on your data. So, as always, it's a trade-off, space vs. time. Hope this helps, Geek ya later! (Need expert application development architecture/coding help? Want me to help you invent directory services based on RDBMS? Need some Cloud-fu or some web services? Contact me at: bbalaban, gmail.com)
Follow me on Twitter @LooseleafLLC
This article ©Copyright 2010 by Looseleaf Software LLC, all rights reserved. You may link to this page, but may not copy without prior approval.
Bob Balaban February 9 2011 06:34:34 AMGreetings, Geeks! Suffering from post-Lotusphere let-down? Never fear, sign up now for "IDoSphere"! It's cheap, it's got great content, and it's all online, no need to leave the comfort of your own desk. Register HERE for the special 10% discount, use the coupon code IDS2011BB My session is: Debugging Notes Java Agents With Eclipse There is still no Java debugger (that humans can use) built into Domino Designer. If you want to build a complex Notes or Domino agent using Java, how can you debug it without making major code changes between debug and production modes? Come to this session to learn how to use a technique called the "2-Headed Beast" - a way of writing a Java program so that it can be run both in debug mode from within Eclipse, and then pasted into Designer with zero code modifications. This session assumes a working knowledge of Java, but you need not be a guru to make friends with the 2-headed beast! I'm doing this live-in-the-studio with live Q&A. http://bit.ly/IdoSphereDiscount IDS2011BB Geek ya Online! | |