Ice.Application feature requests

[bartley]

For the Java language mapping, I'd like to request the following for the Ice.Application class:

1) New overloaded main() methods with support for loading Ice properties files stored in jars. Perhaps an InputStream, or at least a java.util.Properties instance. It's pretty common practice to store properties files in jars, which isn't currently very convenient with Ice (see http://www.zeroc.com/vbulletin/showt...=8906#post8906). I'd expect the load() method in Ice.Properties to be overloaded in a similar way.

2) Javadoc comments instead of //-style comments. Several of the comments in Ice.Application are very important to the user. Comments that aren't javadoc don't do me any good unless I know they're there.

Speaking of the comments in Ice.Application, one of them reads:

One limitation of this class is that there can only be one Application instance, with one global Communicator, accessible with this communicator() operation. This limitiation is due to how the signal handling functions below operate.

Maybe I just need to look at the code more, but isn't the limitation actually due to _communicator (and associated members and methods) being static? Is there really a need for it to be static? In any case, this comment should definitely be a javadoc comment.

thanks!

[marc]

Originally Posted by bartley

2) Javadoc comments instead of //-style comments. Several of the comments in Ice.Application are very important to the user. Comments that aren't javadoc don't do me any good unless I know they're there.

We'll keep this in mind, but I doubt we will do this anytime soon. We try to keep the source code for the various Ice versions for different languages as similar as possible, including comments. This makes it a lot easier to maintain support for so many languages. For example, we can simply cut&paste comments from one Ice version to another.

Originally Posted by bartley

Maybe I just need to look at the code more, but isn't the limitation actually due to _communicator (and associated members and methods) being static? Is there really a need for it to be static?

Ice.Application is just a helper class, intended to be used for applications that only require one communicator. For such applications, making the communicator static makes the code less verbose (because you can access the communicator everywhere in your code, without having to pass it around).

Of course you can also write Ice applications without this helper class, or write your own helper class.

[bartley]

We'll keep this in mind, but I doubt we will do this anytime soon. We try to keep the source code for the various Ice versions for different languages as similar as possible, including comments. This makes it a lot easier to maintain support for so many languages. For example, we can simply cut&paste comments from one Ice version to another.

If the motivation is really for ease of cutting & pasting then why not use block comments? That would be easier for cutting & pasting, and still allow you to use javadoc comments for the java folks. And for languages that don't have block comments (if any?), then you still have to muck around anyway with the per-line comment characters (since I doubt they're all the same), so no big loss.

Regardless, my point wasn't really about the style of the comment, but rather that I shouldn't have to read the code to correctly use the code. Using a Javadoc comment would satisfy that goal for at least the Java folks.

Ice.Application is just a helper class, intended to be used for applications that only require one communicator. For such applications, making the communicator static makes the code less verbose (because you can access the communicator everywhere in your code, without having to pass it around).

But is it necessary? Why not make it non-static and not a singleton and let the developer decide whether it should be statically accessible? For example, something like this:

public final class ChatClient extends Ice.Application()
   {
   private static final ChatClient INSTANCE = new ChatClient();
   static
      {
      // some sort of initialization of INSTANCE here...
      }
   
   public static ChatClient getInstance()
      {
      return INSTANCE;
      }

   // ...
   }

// code in other classes which need the communcator could get it like this:
ChatClient.getInstance().getCommunicator();

Wouldn't such an approach satisfy both the people who need only one communicator as well those who want/need multiples?

Sorry, I'm not trying to be argumentative. Maybe there's some other technical reason that I'm missing, but I think avoidance of code verbosity is a poor motivation for the current design.

[marc]

It is simply a design choice. Ice.Application is for applications that require only one communicator, and it is optimized for this use. As I wrote above, it's just a helper class, and you can choose not to use it if it doesn't fit your requirements. Have a look at the Ice manual (chapter 3.4) for code that initializes an Ice application directly, without the Ice.Application helper class.

[marc]

Originally Posted by bartley

If the motivation is really for ease of cutting & pasting then why not use block comments? That would be easier for cutting & pasting, and still allow you to use javadoc comments for the java folks. And for languages that don't have block comments (if any?), then you still have to muck around anyway with the per-line comment characters (since I doubt they're all the same), so no big loss.

I don't think this is a good idea, because this would give our code comments the status of a reference documentation. However, the comments were neither intended to be used as reference, nor would they be complete enough to serve as reference. The comments are only for the developers of Ice or for students of the source code, but not for application developers. The reference documentation for Ice application developers is the Ice manual.

Originally Posted by bartley

Regardless, my point wasn't really about the style of the comment, but rather that I shouldn't have to read the code to correctly use the code. Using a Javadoc comment would satisfy that goal for at least the Java folks.

Ice.Application is described in detail in the Ice manual (chapter 12.3.1), including a description of its limitations. There should be no reason to read the source code comments to use Ice.Application. If the documentation in the manual is incomplete, please let us know what's missing.