Difference between revisions of "Documentation/DevGuide/ProUNO/Java/Mapping of Services"

Latest revision as of 12:54, 23 December 2020

A new-style services is mapped to a public Java class with the same name. The class has one or more public static methods that correspond to the explicit or implicit constructors of the service.

For a new-style service with a given interface type XIfc, an explicit constructor of the form

  name([in] Type1 arg1, [in] Type2 arg2) raises (Exception1, ..., ExceptionN);

is represented by the Java method

  public   static XIfc name(com.sun.star.uno.XComponentContext context, 
  Type1 arg1, Type2 arg2) 
     throws Exception1, ..., ExceptionN { ... }

A UNO rest parameter (any...) is mapped to a Java rest parameter (java.lang.Object...) in Java 1.5, and to java.lang.Object[] in older versions of Java.

If a new-style service has an implicit constructor, the corresponding Java method is of the form

  public static XIfc create(com.sun.star.uno.XComponentContext context) { ... }

The semantics of both explicit and implicit service constructors in Java are as follows:

• The first argument to a service constructor is always a com.sun.star.uno.XComponentContext, which must be non-null. Any further arguments are used to initialize the created service (see below).

• The service constructor first uses getServiceManager to obtain a service manager (a com.sun.star.lang.XMultiComponentFactory) from the given component context.

• The service constructor then uses createInstanceWithArgumentsAndContext to create a service instance, passing it the list of arguments (without the initial XComponentContext). If the service constructor has a single rest parameter, its sequence of any values is used directly, otherwise the given arguments are made into a sequence of any values. In the case of an implicit service constructor, no arguments are passed, and createInstanceWithContext is used instead.

• If any of the above steps fails with an exception that the service constructor may throw (according to its exception specification), the service constructor also fails by throwing that exception. Otherwise, if any of the above steps fails with an exception that the service constructor may not throw, the service constructor instead fails by throwing a com.sun.star.uno.DeploymentException. Finally, if no service instance could be created (because either the given component context has no service manager, or the service manager does not support the requested service), the service constructor fails by throwing a com.sun.star.uno.DeploymentException. The net effect is that a service constructor either returns a non-null instance of the requested service, or throws an exception; a service constructor will never return a null instance.

Old-style services are not mapped into the Java language binding.