RuleManager readAs method throws ClassCastException. Needs more clarity on usage.

[georgeajit]

While attempting to test RuleManager class' readRuleAs method, multiple Java I/O classes were utilized to read a rule from the server in an XML representation.

Some of the Java I/O class usage threw a ClassCastException. The readRuleAs method usage needs to be clarified and Java Docs documentation to be more specific about which class or specific Java IO package (hierarchy) needs to be used.

As per the current RuleManager documentation, we have

<T> T readRuleAs(String ruleName,
               Class<T> as)
             throws ResourceNotFoundException,
                    ForbiddenUserException,
                    FailedRequestException

Reads a rule from the server in an XML representation provided as an object of an IO class. The IO class must have been registered before creating the database client. By default, standard Java IO classes for document content are registered.

Parameters:
    ruleName - name of rule on REST server
    as - the IO class for reading the rule
Returns:
    an object of the IO class with the rule

Here is the test method snippet used:

@Test   
    public void testRuleManagerReadAs() throws IOException, ParserConfigurationException, SAXException, XpathException, TransformerException
    {   
        System.out.println("Running testRuleManagerReadAs");
        String ruleName1 = "RULE-TEST-1";
        String ruleName2 = "RULE-TEST-2";

        String[] filenames = {"constraint1.xml", "constraint2.xml", "constraint3.xml", "constraint4.xml", "constraint5.xml"};

        DatabaseClient client = DatabaseClientFactory.newClient("localhost", 8011, "rest-admin", "x", Authentication.DIGEST);

        // write docs
        for(String filename : filenames)
        {
            writeDocumentUsingInputStreamHandle(client, filename, "/raw-alert/", "XML");
        }

        // create a manager for configuring rules
        RuleManager ruleMgr = client.newRuleManager();

        // create handle
        InputStreamHandle ruleHandle1 = new InputStreamHandle();
        InputStreamHandle ruleHandle2 = new InputStreamHandle();

        // get the rule file
        InputStream inputStream1 = new FileInputStream("src/test/java/com/marklogic/client/functionaltest/rules/alertRule1.xml");
        InputStream inputStream2 = new FileInputStream("src/test/java/com/marklogic/client/functionaltest/rules/alertRule2.xml");

        ruleHandle1.set(inputStream1);
        ruleHandle2.set(inputStream2);

        // write the rule to the database
        ruleMgr.writeRule(ruleName1, ruleHandle1);
        ruleMgr.writeRule(ruleName2, ruleHandle2);

        // create a manager for document search criteria
        QueryManager queryMgr = client.newQueryManager();

        // specify the search criteria for the documents
        String criteria = "atlantic";
        StringQueryDefinition querydef = queryMgr.newStringDefinition();
        querydef.setCriteria(criteria);

        // create a manager for matching rules
        RuleManager ruleMatchMgr = client.newRuleManager();

        // Test for readRule
        RuleDefinition ruleReadDef1 = ruleMatchMgr.readRule(ruleName1, new RuleDefinition());
        assertTrue("Rule Manager read name method asserts", ruleName1.equalsIgnoreCase(ruleReadDef1.getName()));
        assertTrue("Rule Manager read description method asserts", ruleReadDef1.getDescription().equalsIgnoreCase("rule for test1"));

        // Test for readRuleAs
        String bufCurrentLine = null;
        StringBuffer srtBuf = new StringBuffer();
        File rule2ReadAsFile = ruleMatchMgr.readRuleAs(ruleName2, File.class);

        BufferedReader bufInputStream = new BufferedReader(new FileReader(rule2ReadAsFile));
        while ((bufCurrentLine = bufInputStream.readLine()) != null) {
            srtBuf.append(bufCurrentLine);
            System.out.println(bufCurrentLine);
        }
// Close all streams after assert checks are done.


        // match the rules against the documents qualified by the criteria
        RuleDefinitionList matchedRules = ruleMatchMgr.match(querydef, new RuleDefinitionList());

        System.out.println(matchedRules.size());

        String expected = "";

        // iterate over the matched rules
        Iterator<RuleDefinition> ruleItr = matchedRules.iterator();
        while (ruleItr.hasNext()) 
        {
            RuleDefinition rule = ruleItr.next();
            System.out.println(
                    "document criteria "+criteria+" matched rule "+
                            rule.getName()+" with metadata "+rule.getMetadata()
                    );
            expected = expected + rule.getName() + " - " + rule.getMetadata() + " | ";
        }

        System.out.println(expected);

        assertTrue("incorrect rules", expected.contains("RULE-TEST-1 - {rule-number=one}")&& expected.contains("RULE-TEST-2 - {rule-number=two}"));

        // release client
        client.release();       
    }

Using java.io.File class works. However other java.io class throws exceptions.

Here is the console output (exception trace when java.io.BufferedInputStream is used)

java.lang.ClassCastException: com.sun.jersey.client.apache4.ApacheHttpClient4Handler$HttpClientResponseInputStream cannot be cast to java.io.BufferedInputStream
    at com.marklogic.client.functionaltest.TestDatabaseClientConnection.testRuleManagerReadAs(TestDatabaseClientConnection.java:653)
    at sun.reflect.NativeMethodAccessorImpl.invoke0(Native Method)
    at sun.reflect.NativeMethodAccessorImpl.invoke(Unknown Source)
    at sun.reflect.DelegatingMethodAccessorImpl.invoke(Unknown Source)
    at java.lang.reflect.Method.invoke(Unknown Source)
    at org.junit.runners.model.FrameworkMethod$1.runReflectiveCall(FrameworkMethod.java:47)
    at org.junit.internal.runners.model.ReflectiveCallable.run(ReflectiveCallable.java:12)
    at org.junit.runners.model.FrameworkMethod.invokeExplosively(FrameworkMethod.java:44)
    at org.junit.internal.runners.statements.InvokeMethod.evaluate(InvokeMethod.java:17)
    at org.junit.runners.ParentRunner.runLeaf(ParentRunner.java:271)
    at org.junit.runners.BlockJUnit4ClassRunner.runChild(BlockJUnit4ClassRunner.java:70)
    at org.junit.runners.BlockJUnit4ClassRunner.runChild(BlockJUnit4ClassRunner.java:50)
    at org.junit.runners.ParentRunner$3.run(ParentRunner.java:238)
    at org.junit.runners.ParentRunner$1.schedule(ParentRunner.java:63)
    at org.junit.runners.ParentRunner.runChildren(ParentRunner.java:236)
    at org.junit.runners.ParentRunner.access$000(ParentRunner.java:53)
    at org.junit.runners.ParentRunner$2.evaluate(ParentRunner.java:229)
    at org.junit.internal.runners.statements.RunBefores.evaluate(RunBefores.java:26)
    at org.junit.internal.runners.statements.RunAfters.evaluate(RunAfters.java:27)
    at org.junit.runners.ParentRunner.run(ParentRunner.java:309)
    at org.eclipse.jdt.internal.junit4.runner.JUnit4TestReference.run(JUnit4TestReference.java:50)
    at org.eclipse.jdt.internal.junit.runner.TestExecution.run(TestExecution.java:38)
    at org.eclipse.jdt.internal.junit.runner.RemoteTestRunner.runTests(RemoteTestRunner.java:459)
    at org.eclipse.jdt.internal.junit.runner.RemoteTestRunner.runTests(RemoteTestRunner.java:675)
    at org.eclipse.jdt.internal.junit.runner.RemoteTestRunner.run(RemoteTestRunner.java:382)
    at org.eclipse.jdt.internal.junit.runner.RemoteTestRunner.main(RemoteTestRunner.java:192)

And when FileReader class is used:

java.lang.ClassCastException: java.io.InputStreamReader cannot be cast to java.io.FileReader

[sammefford]

By IO classes we mean the ones registered by handles (things that implement AbstractReadHandle or AbstractWriteHandle).

Generally each handle registers one class that it handles. For example, FileHandle handles objects of type java.io.File. Two handles allow additional custom objects to be registered with them: JAXBHandle and JacksonDatabindHandle. To learn more, read "Registering New IO Representations for Shortcut Methods" here. Also see Erik's excellent blog post.

Kim, do we have a section in docs explaining this? If not, should we add one?

I'll keep this task as a javadoc task to add a link to all *As methods.

[kcoleman-marklogic]

I doubt we have anything about this in the book. The handle documentation predates my involvement, but I've never heard of this registry thing nor the stuff Erik talks about in his blog post. Everything in the book is handle based, AFAIK.

If you think it is an important concept to cover that is not adequately addressed, then please create a doc bug (preferably in bugtrack). It would be helpful if you're clear about what needs covering in the bug. Do I just need to repeats what's already in the javadoc, or is there a wider topic about I/O that's missing, or is this something specific to reading and writing triples?

FWIW, the book currently only ever talks about and demonstrates operations through handles. I don't really understand if this is just an alternative or what, or which approach is preferred, but perhaps it'll be more clear when I have time to read Eriks blog post thoroughly.

This isn't terribly likely to be addressed in the dev guide before 9.0-1.