Skip to content

JAVA-1316: Naming strategy support in mapper configuration level - #778

Closed
avivcarmis wants to merge 13 commits into
apache:java1310from
avivcarmis:java1316
Closed

avivcarmis wants to merge 13 commits into
apache:java1310from
avivcarmis:java1316

Conversation

@avivcarmis

Copy link
Copy Markdown

Hi (:
So this is what i eventually thought to be the best design for a solution for Java-1316. First, two quick examples, then some key notes for feedback.

Example 1: camelCase to snake_case
Consider this class:

@Table(name = "foo")
public class Foo {

    @PartitionKey
    private int myXmlParser;

    private int other;

    public int getMyXmlParser() {
        return myXmlParser;
    }

    public void setMyXmlParser(int myXmlParser) {
        this.myXmlParser = myXmlParser;
    }

    public int getOther() {
        return other;
    }

    public void setOther(int other) {
        this.other = other;
    }

}

and this table:
CREATE TABLE foo (my_xml_parser int primary key, other int)

Then in order to automatically match the two, we have to bootstrap a mapper configuration like this:

MapperConfiguration conf = new MapperConfiguration();
conf.getNamingStrategy()
        .setJavaConvention(new CommonNamingConventions.LowerCamelCase())
        .setCassandraConvention(new CommonNamingConventions.LowerSnakeCase());
MappingManager mappingManager = new MappingManager(session(), conf);

Or like this (whichever seems more intuitive):

MapperConfiguration conf = new MapperConfiguration();
conf.setNamingStrategy(new NamingStrategy(
        new CommonNamingConventions.LowerCamelCase(),
        new CommonNamingConventions.LowerSnakeCase()
));
MappingManager mappingManager = new MappingManager(session(), conf);

Example 2: camelCase with ignorable prefixes
It is a common practice in Java to use a fixed prefix for all class member names. Let's now consider class Foo2 and the table foo defined above

@Table(name = "foo")
public class Foo2 {

        @PartitionKey
        private int mMyXmlParser;

        private int mOther;

        public int getmMyXmlParser() {
            return mMyXmlParser;
        }

        public void setmMyXmlParser(int mMyXmlParser) {
            this.mMyXmlParser = mMyXmlParser;
        }

        public int getmOther() {
            return mOther;
        }

        public void setmOther(int mOther) {
            this.mOther = mOther;
        }

}

Then in order to automatically match the two, we have to bootstrap a mapper configuration with java convention of lower case with ignorable prefix of "m":

MapperConfiguration conf = new MapperConfiguration();
conf.getNamingStrategy()
        .setJavaConvention(new CommonNamingConventions.LowerCamelCase("m"))
        .setCassandraConvention(new CommonNamingConventions.LowerSnakeCase());
MappingManager mappingManager = new MappingManager(session(), conf);

Or like this (whichever seems more intuitive):

MapperConfiguration conf = new MapperConfiguration();
conf.setNamingStrategy(new NamingStrategy(
        new CommonNamingConventions.LowerCamelCase("m"),
        new CommonNamingConventions.LowerSnakeCase()
));
MappingManager mappingManager = new MappingManager(session(), conf);

Lastly, some important things to note:

  • A predefined collection of naming conventions is available under CommonNamingConventions class - lowerCamelCase, UpperCamelCase, lower_snake_case, UPPER_SNAKE_CASE, lowercase, lower-kebab-case (currently cannot be used either as java properties or as cassandra columns) and UPPER-KEBAB-CASE (likewise). In a case where a user uses a different naming convention, he should implement the NamingConvention interface and pass an instance of it to the MapperConfiguration.NamingStrategy object. More info available in the javadoc of NamingConvention and CommonNamingConventions.
  • In PropertyMapper::inferColumnName the last line was quating only case-sensetive values but not lower-cased values. Is there a down side to always quote column names? Currently it does, if that is a problem, i can add a regexp match to determine whether all chars are lower-cased in the resulted column name.
  • In case where a user uses an uncommon convention in which cassandra naming convention is camel case with upper case abbreviations (e.g. myXMLParser), and java naming convention is not - then there's no way to detect abbreviations and user has to explicitly declare them [e.g. @Column(name = "myXMLParser")].
  • In case where a user uses an uncommon convention in which cassandra naming convention is camel case, and java naming convention is not - then there's also the case of conventional member prefixes (e.g. mMyXmlParser, m_myXmlParser, _myXmlParser) who have to be expicitly declared.
  • To allow backwards compatibility for users who have used the default camelCase - to - lowercase strategy which exists today (e.g. having a property named myXmlParser and a matching cassandra column named myxmlparser), the default cassandra naming convention is set to LowerCase, although the common strategy should probably be set to camelCase - to - snake_case.
  • To allow additional backwards compatibility , if a user defines a @Column or @Field annotation, and sets either column name or case sensitive values, naming strategy will be bypassed for this property and previous result should occur.
  • When constructing a new CamelCase parser, you may supply an array of member naming prefixes to ignore (e.g. mMyXmlParser, m_myXmlParser, _myXmlParser). In order to be 100% backwards compatible, if you do not supply them , the current default none. This means that by default, "m_myXmlParser" is mapped to "m_myxmlparser" instead of just "myxmlparser". If a user does want those he has to explicitly pass them to the constructor [e.g. new CamelCase("_", "m", "m_")]. This is more of a product question but you may decide to skip 100% backwards compatible (if we can assume no one has named his DB columns "m_my_xml_parser") and then have this kickass support by default (:

@avivcarmis

Copy link
Copy Markdown
Author

Regarding the 2nd note (column quoting) it raised issues within the driver so I added the regexp validation. Column names will be quoted only when non lowercase alphanumeric or underscore (as mentioned in the docs)

@adutra adutra added this to the 3.2.0 milestone Dec 29, 2016
@olim7t olim7t closed this Feb 16, 2017
@avivcarmis

Copy link
Copy Markdown
Author

@olim7t you've closed this one too, still relevant?

@adutra

adutra commented Feb 17, 2017

Copy link
Copy Markdown
Contributor

Re-opening (was closed by mistake).

@adutra adutra reopened this Feb 17, 2017

@adutra adutra left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Very extensive and solid work, congratulations. At first glance one could wonder why so much code for "just" naming conventions, but I guess the devil was in the details, as usual.


/**
* Represent a naming convention (e.g. snake_case, camelCase, etc...) to be used when
* auto-translating java property names to cassandra column names and vise-versa.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Small typo: "vice versa"

private NamingConvention cassandraConvention;

public NamingStrategy(NamingConvention javaConvention, NamingConvention cassandraConvention) {
setJavaConvention(javaConvention);

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Don't call public setters from a constructor, assign to fields directly.

* @param input value to translate
* @return Java naming convention translation of the input
*/
public String toJava(String input) {

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is not covered by tests currently.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Nor is it used anywhere in the production code. Do we really need it?

Copy link
Copy Markdown
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I went for designing an independent interface for handling translation of naming conventions to it seemed trivial to implement both ways. If we prefer to avoid unused code we can remove it. If in the future we find a need to translate Cassandra column names to java fields, as you can see, the implementation is 3 lines.
So i think we can go for removing right now.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

So i think we can go for removing right now.

Yes please. We need to be a bit conservative at this stage because once a line of code is contributed to the driver, it means it needs to be maintained :)

* Enables the naming strategy, allowing it to auto translate properties that haven't been
* explicitly translated.
*/
public void enable() {

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Sorry but isn't this going a bit too far? Why would someone enable then disable the naming strategy? IMO it should be always enabled.

Copy link
Copy Markdown
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Let's discuss below.

* across different naming conventions.
*/
@SuppressWarnings("unused")
public class PropertyNamingStrategyTest extends CCMTestsSupport {

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The following conventions seem untested: UpperCamelCase, UpperSnakeCase, LowerKebabCase, UpperKebabCase.

I have a mixed feeling about the "kebab" variants.

First of all, this "kebab" name: as per this SO question it seems we could call it "lisp-case" or "spinal-case" as well. If for nothing else, I'd rather pay hommage to a beautiful programming language than to some greasy – yet savory – meat skewers :)

Secondly, as you said, the kebab variants are not possible in Java. They could be possible in Cassandra, provided that the column name is double-quoted: "MY-COLUMN" is a valid CQL identifier. This should be explicitly tested for.

I'd suggest here the use of a @DataProvider annotation that would test all the possible valid combinations of Java + Cassandra naming conventions.

Copy link
Copy Markdown
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yeah i followed Jackson on this one and wondered if you'll like it or not. (:
BTW Guava called it hyphen.
I think we can go for UPPER-LIPS-CASE and lower-lisp-case.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think we can go for UPPER-LIPS-CASE and lower-lisp-case

Yes – provided you spell it LISP, not LIPS :D

@olim7t

olim7t commented Feb 17, 2017

Copy link
Copy Markdown
Contributor

Yes, sorry for closing, it was again because it's targeted to my now-obsolete java1310 branch. Btw this will probably bothersome when we merge the PRs, but no need to close and re-open against 3.x, we'll handle it manually.

}
}
return caseSensitive ? Metadata.quote(columnName) : columnName.toLowerCase();
return columnName.matches(UNQUOTED_COLUMN_NAME_REGEXP) ? columnName : Metadata.quote(columnName);

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I wonder if we could quote everything by default here, I think these names are only used for internal requests.

@avivcarmis avivcarmis Feb 18, 2017 •

Copy link
Copy Markdown
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I initially tried to as i wrote in my first comment, but it broke some other places within the mapper (i can look them up although i can't recall right now) that were expecting lower cases not to be quoted.

properties.put(property.getName(), property);
if (!properties.containsKey(property.getName())) {
properties.put(property.getName(), property);
}

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is this fix related to JAVA-1310 or 1316?

* @param input value to translate
* @return Java naming convention translation of the input
*/
public String toJava(String input) {

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Nor is it used anywhere in the production code. Do we really need it?


private NamingConvention javaConvention;

private NamingConvention cassandraConvention;

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I suggest making these fields final, and removing the getters and setters. The naming strategy is something that users will set at the beginning, and never worry about later. I see little value in accessing the conventions, let alone changing them at runtime.

Copy link
Copy Markdown
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

So we can remove setters and enable, disable methods.
One thing is design how should users disable naming strategy all together (in case they have their cassandra column names exactly like their java fields). As you suggested below we probably want to define a NamingStrategy singleton to bypass naming. Only question is whether this is a trivial approach for the user, i.e.:

config.setNamingStrategy(NamingStrategy.PASS_THROUGH);

What do you think?

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

disable naming strategy all together

I don't think users would actually want that, there should always be a naming strategy in place.

The question is: what should be the default strategy? I think we need to prioritize continuity and favor a strategy that actually yields the same results as currently, without any need to customize the default settings. In other words: favor convention over configuration. So I think indeed we need a "passthrough" strategy as our default.

Copy link
Copy Markdown
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@adutra To my understanding the default today is just converting to lower-case (i.e. converting myXmlParser simply to myxmlparser), this means that the default should be LowerCamelCase to LowerCase which will provide the same result. if we pass through we are to output myXmlParser which might break some code for migrating developers. Right?

* @return whether or not the given naming convention returns exactly
* the same output as this
*/
boolean equals(NamingConvention other);

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It seems that this is only used to optimize the conversions in NamingStrategy when the two conventions are the same.
We could instead have a PassThroughNamingStrategy that contains null conventions and overrides toCassandra (and toJava if we keep it). It could even be a unique instance of an anonymous class exposed as a singleton, such as NamingStrategy.PASS_THROUGH.
This way we get rid of equals in all the implementations.

Copy link
Copy Markdown
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Let's discuss above.

* <li>{@code true} - myXMLParser</li>
* </ul>
*/
public static class LowerCamelCase extends CamelCase {

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

More documentation on these classes would be appreciated, and also on the constructors as some of them aren't clear to me (i.e. It isn't immediately clear to me what ignorablePrefixes means)

public static class TestRecommendedSettings {

@PartitionKey
private int mMyXmlParser;

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Sort of confused how this works. Since the Java Convention is LowerCamelCase (new CommonNamingConventions.LowerCamelCase("m", "_")) should this be mmyXmlParser, as the first m would be stripped and myXmlParser is LowerCamelCase (vs MyXmlParser which would be UpperCamelCase)?

Copy link
Copy Markdown
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

So the corresponding table snake_case_table contain the fields my_xml_parser and other. If I am a sworn android developer, i'd probably put m in the beginning of all my private fields, or i may have any other blind faith like putting _ as i personally like. But there many other examples. Anyways, in this test we want to tell the mapper - each time you spot m or _ in the beginning of a field name (or a getter/setter), strip it down. then convert to the output naming conversion.
So what the mapper does here is actually receive mMyXmlParser as input, strip it to myXmlParser, and then transform to snake case (the output strategy) which results in my_xml_parser. Same for _other field.

Practically, you should use this option only if you do have a constant prefix you use, and only for the one you use. I don't think anyone actually uses both "_" and "m" as prefixes but the test covers them both. although some extreme conventions have many different prefixes depending on the type of the variable, and we can support it too.

@avivcarmis

avivcarmis commented Feb 24, 2017 •

Copy link
Copy Markdown
Author

Summing up:

1. Fix typo.
2. Fix field assignment.
3. remove toJava method.
4. rename lowerKebabCase and UpperKebabCase to LowerLispCase and UpperLispCase.
5. Following this one: Create a factory class (or use 1310's) make all fields final and remove setters, add an intuitive support for disabling naming strategy (so that cassandra column naming will reflect exactly java field names). I wanted to wait with that until 1310 is done so we have a clear vision of the factory interface.
6. More docs for naming convention classes.
7. test all possible conversion combinations: That is, all combinations of classes within CommonNamingConventions may be tested. Note that we have 7 out of the box conventions so this means up to 49 tests. We can skip tests that convert from LowerLispCase and UpperLispCase since they cannot be used for java fields, and also we can skip most of conversion from and to the same conversion as discussed here with the exception of converting camel case with certain settings (m_ prefix for example) to camel case with other settings (no prefixes for example). Bottom line - let's save that one for last.
8. Rebasing on top of final 1310 result.

@avivcarmis

avivcarmis commented Mar 3, 2017 •

Copy link
Copy Markdown
Author

A new reflection I've had. Got some inputs that seemed like CamelCase conventions are kind of hard to follow. In contrast to other convention implementations, LowerCamelCase and UpperCamelCase can take parameters in their constructors since they can support options that don't exist in other conventions.
The two supported options are:

  • Fixed field prefixes. For example, you may prefix all your class fields with "m" like Android developers do. In that case you want mMyxmlParser to be translated to my_xml_parser. This is supported by sending "m" when constructing a new camel case instance.
  • Abbreviation casing - e.g. myXmlParser vs myXMLParser. both are valid. this is needed, for example, if you java convention is lower camel case with upper cased abbreviations (e.g. myXMLParser) and your cassandra convention is upper camel case with upper cased abbreviations (e.g. MyXMLParser) - otherwise, the whole XML part would translate to Xml.

The latter option seems to be less intuitive. I think that if someone is crazy enough to have cassandra convention set to something other than lower snake case and other than PASS_THROUGH, then he would require this support. On the other hand, he has the ability to define his own naming convention by implementing NamingConvention on his own and he can manage. If we believe abbreviations make the whole interface less intuitive, we can simply drop this feature.

Regarding prefixes, since this is rather common - i think we should keep it.
Thoughts?

@tolbertam

Copy link
Copy Markdown
Contributor

Note: these changes (with modifications for recent api changes) were applied to #814.

@tolbertam

Copy link
Copy Markdown
Contributor

Closing this since work has been moved to #814

@tolbertam tolbertam closed this Mar 15, 2017
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants