Standard usage

boolean useSSL = false;
ServiceClient client = new ServiceClient("localhost", 8080, useSSL);

PublicAuthenticationService authService = client.getPort(PublicAuthenticationService.class);
if (!authService.isAuthenticated())
        authService.authenticate("guest", new char[] {'p', 'w'});

PublicFileService fileService = client.getPort(PublicFileService.class);
FileInformation info = fileService.getFileInformation(new FileIdentifier(...));

Notes:

• The ServiceClient instance preserves the user session using cookies. Multiple instances are required to create multiple client sessions.
  Multiple instances will not lead to multiple client sessions in case of a global cookie handler is installed inside the java environment (see below).
• Access to the interfaces is obtained via the method getPort(Class<? extends Service> cls).
  The ports returned by this method implement any interface that derives from the group interface: com.trendmicro.grid.acl.Service (as also reflected in the method signature).

  The java compiler (or a proper IDE) validates that only correct interface classes can be specified. Using IntelliJ IDEA, smart auto-complete (CTRL + SHIFT + SPACE) can be used in order to obtain a list of matching interface classes when placing the caret at the location of the method's first argument.

• The client instance is heavy weight when compared to the ports (implementations behind the Service interfaces obtained via the getPorts(...) method). It's in general wise to reuse the instance when possible.
• All instances are thread safe, multiple threads cause the client to open multiple connections and issue calls concurrently.
• The official GRID is reachable via "mygacl.trendmicro.com" (public & protected services) and "gacl.trendmicro.com" (public services only). The port is always 443 and useSSL must be 'true'.

Authenticate the session

Authentication may or may not be required depending on the server setup and service that is used. As a general rule, service interface methods throwing an AuthenticationException need an authenticated client session, for the case that authentication is enabled on the server side.

GACL 1.0 does not require authentication of any sort, but clients must implement the authentication code below if they want to stay compatible with future releases.

ServiceClient client = new ServiceClient("gacl.trendmicro.com", 443, true);

PublicAuthenticationService authService = client.getPort(PublicAuthenticationService.class);
if (!authService.isAuthenticated()) {
        String username = "guest";
        char[] password = "secret".toCharArray();
        if (!authService.authenticate(username, password))
                throw new IllegalArgumentException("Username or password was incorrect.");
}

Dealing with paged lists

All possibly large collections that can be retried via service interfaces are paged in order to avoid out of memory exceptions with large result sets and to improve caching under the assumption that mostly the top most entries are fetched.

All relevant list pages (or list chunks) derive from the abstract base class AbstractListPage<E> and can be handled with equal code.

The following example illustrates the correct usage:

ServiceClient client = new ServiceClient("gacl.trendmicro.com", 443, true);
PublicPackageService packageService = client.getPort(PublicPackageService.class);

String name = "trendmicro:officescan:10.0.0.1:x86:en";

int pageNumber = 0;
NamedFileIdentifierListPage page;
do {
        page = packageService.getFilesContainedInPackageByName(name, pageNumber);
        pageNumber++;

        for (NamedFileIdentifier id : page.getElements()) {
                   byte[] sha1 = id.getSHA1Hash();
                   String filename = id.getFileName();
                   String sha1AsHexString = Hex.encode(sha1);
                   System.out.println(name + ":" + filename + "(sha1=" + sha1AsHexString + ")");
        }
} while(!page.isLastPage());

Dealing with BatchCollections

From version >= 1.2, some SOAP interfaces require the collection class BatchCollection<E> as input parameter.

Batch collections can either be created directly or they can be created out of an existing list through wrapping. The methods "BatchCollection.of(Collection<E>)" and "BatchCollection.chunksOf(List<E>)" do not copy the existing collection, they simply wrap it which means it is in general no performance penalty to convert an existing list.

Examples:

List<FileIdentifiers> inputIdentifiers = ....

ServiceClient client = new ServiceClient("gacl.trendmicro.com", 443, true);
PublicFileService fileService = client.getPort(PublicFileService.class);

// Use only if inputIdentifiers is within the allowed batch size (= 100 elements by default)
Collection<Boolean> results = fileService.isFilesKnown(BatchCollection.of(inputIdentifiers));

// Use if batch size is using the default of 100 elements on the remote server instance.
for (BatchCollection<FileIdentifiers> chunk : BatchCollection.chunksOf(inputIdentifiers)) {
    Collection<Boolean> results = fileService.isFilesKnown(chunk);
    ...
}

// Is safe to use with any batch settings and list sizes
Collection<Boolean> results = BatchCollection.invokeOnChunksOf(inputIdentifiers,
    new BatchCollection.Invoker<FileIdentifier, Collection<Boolean>>() {
        public Collection<Boolean> invoke(BatchCollection<FileIdentifier> chunk) {
            return fileService.isFilesKnown(chunk);
        }
    });

Note: In contrast to the simple wrapping methods, invokeOnChunksOf internally handles exceptions when the batch size was exceeded and adjusts the chunk size that is used with the remote calls.

Toggle compressed communication

Toggles whether the service client accepts or sends GZIP compressed SOAP messages.

Note: Currently the server accepts compressed requests but it will not send compressed responses as this feature is disabled on the GACL server. Setting "compressResponses" to true however indicates that the client would prefer compressed responses as soon as the server offers them.

ServiceClient client = new ServiceClient("gacl.trendmicro.com", 443, true);
client.getContext().setCompressRequests(true);
client.getContext().setCompressResponses(true);

Installing a global cookie handler

Installs a global cookie handler in order to catch all URL transfers and put them under the same client session.

This is required to make uploads and downloads work correctly (future version may not need this).

Note: By installing a global cookie handler, all ServiceClient instances run under the same user session.

ServiceClient client = new ServiceClient("gacl.trendmicro.com", 443, true);
client.getContext().getSessionHandler().registerAsSystemDefault();