refactor the selector api to scope factories (#289)

* refactor the selector api to scope factories

Rather than have the service selector offer an api of
include* or exclude* for each of its recognized
data scopes, instead expose a set of factory funcs
for each datat scope and a smaller api of functions
that can consume those scopes.

src/pkg/selectors/exchange.go

@@ -69,8 +69,53 @@ func (s Selector) ToExchangeRestore() (*ExchangeRestore, error) {
 // -------------------
 // Exclude/Includes
 
-func contactScope(u, f string, vs ...string) map[string]string {
+// Include appends the provided scopes to the selector's inclusion set.
-	return map[string]string{
+func (s *exchange) Include(scopes ...exchangeScope) {
+	if s.Includes == nil {
+		s.Includes = []map[string]string{}
+	}
+	for _, sc := range scopes {
+		sc = extendExchangeScopeValues(All, sc)
+		s.Includes = append(s.Includes, map[string]string(sc))
+	}
+}
+
+// Exclude appends the provided scopes to the selector's exclusion set.
+// Every Exclusion scope applies globally, affecting all inclusion scopes.
+func (s *exchange) Exclude(scopes ...exchangeScope) {
+	if s.Excludes == nil {
+		s.Excludes = []map[string]string{}
+	}
+	for _, sc := range scopes {
+		sc = extendExchangeScopeValues(None, sc)
+		s.Excludes = append(s.Excludes, map[string]string(sc))
+	}
+}
+
+// completes population for certain scope properties, according to the
+// expecations of Include and Exclude behavior.
+func extendExchangeScopeValues(v string, sc exchangeScope) exchangeScope {
+	switch sc.Category() {
+	case ExchangeContactFolder:
+		sc[ExchangeContact.String()] = v
+	case ExchangeMailFolder:
+		sc[ExchangeMail.String()] = v
+	case ExchangeUser:
+		sc[ExchangeContactFolder.String()] = v
+		sc[ExchangeContact.String()] = v
+		sc[ExchangeEvent.String()] = v
+		sc[ExchangeMailFolder.String()] = v
+		sc[ExchangeMail.String()] = v
+	}
+	return sc
+}
+
+// -------------------
+// Scope Factory
+
+func (s *exchange) Contacts(u, f string, vs ...string) exchangeScope {
+	return exchangeScope{
+		scopeKeyGranularity:            Item,
 		scopeKeyCategory:               ExchangeContact.String(),
 		ExchangeUser.String():          u,
 		ExchangeContactFolder.String(): f,
@@ -78,62 +123,27 @@ func contactScope(u, f string, vs ...string) map[string]string {
 	}
 }
 
-// ExcludeContacts selects the specified contacts owned by the user.
+func (s *exchange) ContactFolders(u string, vs ...string) exchangeScope {
-// Use selectors.None to ignore user or folder matching.
+	return exchangeScope{
-func (s *exchange) ExcludeContacts(user, folder string, vs ...string) {
+		scopeKeyGranularity:            Group,
-	s.Excludes = append(s.Excludes, contactScope(user, folder, vs...))
-}
-
-// IncludeContacts selects the specified contacts owned by the user.
-func (s *exchange) IncludeContacts(user, folder string, vs ...string) {
-	s.Includes = append(s.Includes, contactScope(user, folder, vs...))
-}
-
-func contactFolderScope(include bool, u string, vs ...string) map[string]string {
-	wildcard := All
-	if !include {
-		wildcard = None
-	}
-	return map[string]string{
 		scopeKeyCategory:               ExchangeContactFolder.String(),
 		ExchangeUser.String():          u,
 		ExchangeContactFolder.String(): join(vs...),
-		ExchangeContact.String():       wildcard,
 	}
 }
 
-// ExcludeContactFolders selects the specified contactFolders owned by the user.
+func (s *exchange) Events(u string, vs ...string) map[string]string {
-// Use selectors.None to ignore user matching.
-func (s *exchange) ExcludeContactFolders(user string, vs ...string) {
-	s.Excludes = append(s.Excludes, contactFolderScope(false, user, vs...))
-}
-
-// IncludeContactFolders selects the specified contactFolders owned by the user.
-func (s *exchange) IncludeContactFolders(user string, vs ...string) {
-	s.Includes = append(s.Includes, contactFolderScope(true, user, vs...))
-}
-
-func eventScope(u string, vs ...string) map[string]string {
 	return map[string]string{
+		scopeKeyGranularity:    Item,
 		scopeKeyCategory:       ExchangeEvent.String(),
 		ExchangeUser.String():  u,
 		ExchangeEvent.String(): join(vs...),
 	}
 }
 
-// ExcludeEvents selects the specified events owned by the user.
+func (s *exchange) Mails(u, f string, vs ...string) map[string]string {
-// Use selectors.None to ignore user matching.
-func (s *exchange) ExcludeEvents(user string, vs ...string) {
-	s.Excludes = append(s.Excludes, eventScope(user, vs...))
-}
-
-// IncludeEvents selects the specified events owned by the user.
-func (s *exchange) IncludeEvents(user string, vs ...string) {
-	s.Includes = append(s.Includes, eventScope(user, vs...))
-}
-
-func mailScope(u, f string, vs ...string) map[string]string {
 	return map[string]string{
+		scopeKeyGranularity:         Item,
 		scopeKeyCategory:            ExchangeMail.String(),
 		ExchangeUser.String():       u,
 		ExchangeMailFolder.String(): f,
@@ -141,69 +151,23 @@ func mailScope(u, f string, vs ...string) map[string]string {
 	}
 }
 
-// ExcludeMail selects the specified mail messages within the given folder,
+func (s *exchange) MailFolders(u string, vs ...string) map[string]string {
-// owned by the user.
-// Use selectors.None to ignore user or folder matching.
-func (s *exchange) ExcludeMail(user, folder string, vs ...string) {
-	s.Excludes = append(s.Excludes, mailScope(user, folder, vs...))
-}
-
-// IncludeMail selects the specified mail messages within the given folder,
-// owned by the user.
-func (s *exchange) IncludeMail(user, folder string, vs ...string) {
-	s.Includes = append(s.Includes, mailScope(user, folder, vs...))
-}
-
-func mailFolderScope(include bool, u string, vs ...string) map[string]string {
-	wildcard := All
-	if !include {
-		wildcard = None
-	}
 	return map[string]string{
+		scopeKeyGranularity:         Group,
 		scopeKeyCategory:            ExchangeMailFolder.String(),
 		ExchangeUser.String():       u,
 		ExchangeMailFolder.String(): join(vs...),
-		ExchangeMail.String():       wildcard,
 	}
 }
 
-// ExcludeMailFolders selects the specified mail folders owned by the user.
+func (s *exchange) Users(vs ...string) map[string]string {
-// Use selectors.None to ignore user or folder matching.
-func (s *exchange) ExcludeMailFolders(user string, vs ...string) {
-	s.Excludes = append(s.Excludes, mailFolderScope(false, user, vs...))
-}
-
-// IncludeMailFolders selects the specified mail folders owned by the user.
-func (s *exchange) IncludeMailFolders(user string, vs ...string) {
-	s.Includes = append(s.Includes, mailFolderScope(true, user, vs...))
-}
-
-func userScope(include bool, vs ...string) map[string]string {
-	wildcard := All
-	if !include {
-		wildcard = None
-	}
 	return map[string]string{
+		scopeKeyGranularity:   Group,
 		scopeKeyCategory:      ExchangeUser.String(),
 		ExchangeUser.String(): join(vs...),
-		ExchangeContact.String():       wildcard,
-		ExchangeContactFolder.String(): wildcard,
-		ExchangeEvent.String():         wildcard,
-		ExchangeMail.String():          wildcard,
-		ExchangeMailFolder.String():    wildcard,
 	}
 }
 
-// ExcludeUsers selects the specified users.  All of their data is excluded.
-func (s *exchange) ExcludeUsers(vs ...string) {
-	s.Excludes = append(s.Excludes, userScope(false, vs...))
-}
-
-// IncludeUsers selects the specified users.  All of their data is included.
-func (s *exchange) IncludeUsers(vs ...string) {
-	s.Includes = append(s.Includes, userScope(true, vs...))
-}
-
 // ---------------------------------------------------------------------------
 // Destination
 // ---------------------------------------------------------------------------
@@ -290,6 +254,12 @@ func exchangeCatAtoI(s string) exchangeCategory {
 	}
 }
 
+// Granularity describes the granularity (directory || item)
+// of the data in scope
+func (s exchangeScope) Granularity() string {
+	return s[scopeKeyGranularity]
+}
+
 // Category describes the type of the data in scope.
 func (s exchangeScope) Category() exchangeCategory {
 	return exchangeCatAtoI(s[scopeKeyCategory])

src/pkg/selectors/exchange_test.go

@@ -54,7 +54,7 @@ func (suite *ExchangeSourceSuite) TestToExchangeRestore() {
 	assert.NotZero(t, eb.Scopes())
 }
 
-func (suite *ExchangeSourceSuite) TestExchangeSelector_ExcludeContacts() {
+func (suite *ExchangeSourceSuite) TestExchangeSelector_Exclude_Contacts() {
 	t := suite.T()
 	sel := NewExchangeBackup()
 
@@ -65,7 +65,7 @@ func (suite *ExchangeSourceSuite) TestExchangeSelector_ExcludeContacts() {
 		c2     = "c2"
 	)
 
-	sel.ExcludeContacts(user, folder, c1, c2)
+	sel.Exclude(sel.Contacts(user, folder, c1, c2))
 	scopes := sel.Excludes
 	require.Equal(t, 1, len(scopes))
 
@@ -75,7 +75,7 @@ func (suite *ExchangeSourceSuite) TestExchangeSelector_ExcludeContacts() {
 	assert.Equal(t, scope[ExchangeContact.String()], join(c1, c2))
 }
 
-func (suite *ExchangeSourceSuite) TestExchangeSelector_IncludeContacts() {
+func (suite *ExchangeSourceSuite) TestExchangeSelector_Include_Contacts() {
 	t := suite.T()
 	sel := NewExchangeBackup()
 
@@ -86,7 +86,7 @@ func (suite *ExchangeSourceSuite) TestExchangeSelector_IncludeContacts() {
 		c2     = "c2"
 	)
 
-	sel.IncludeContacts(user, folder, c1, c2)
+	sel.Include(sel.Contacts(user, folder, c1, c2))
 	scopes := sel.Includes
 	require.Equal(t, 1, len(scopes))
 
@@ -98,7 +98,7 @@ func (suite *ExchangeSourceSuite) TestExchangeSelector_IncludeContacts() {
 	assert.Equal(t, sel.Scopes()[0].Category(), ExchangeContact)
 }
 
-func (suite *ExchangeSourceSuite) TestExchangeSelector_ExcludeContactFolders() {
+func (suite *ExchangeSourceSuite) TestExchangeSelector_Exclude_ContactFolders() {
 	t := suite.T()
 	sel := NewExchangeBackup()
 
@@ -108,7 +108,7 @@ func (suite *ExchangeSourceSuite) TestExchangeSelector_ExcludeContactFolders() {
 		f2   = "f2"
 	)
 
-	sel.ExcludeContactFolders(user, f1, f2)
+	sel.Exclude(sel.ContactFolders(user, f1, f2))
 	scopes := sel.Excludes
 	require.Equal(t, 1, len(scopes))
 
@@ -118,7 +118,7 @@ func (suite *ExchangeSourceSuite) TestExchangeSelector_ExcludeContactFolders() {
 	assert.Equal(t, scope[ExchangeContact.String()], None)
 }
 
-func (suite *ExchangeSourceSuite) TestExchangeSelector_IncludeContactFolders() {
+func (suite *ExchangeSourceSuite) TestExchangeSelector_Include_ContactFolders() {
 	t := suite.T()
 	sel := NewExchangeBackup()
 
@@ -128,7 +128,7 @@ func (suite *ExchangeSourceSuite) TestExchangeSelector_IncludeContactFolders() {
 		f2   = "f2"
 	)
 
-	sel.IncludeContactFolders(user, f1, f2)
+	sel.Include(sel.ContactFolders(user, f1, f2))
 	scopes := sel.Includes
 	require.Equal(t, 1, len(scopes))
 
@@ -140,7 +140,7 @@ func (suite *ExchangeSourceSuite) TestExchangeSelector_IncludeContactFolders() {
 	assert.Equal(t, sel.Scopes()[0].Category(), ExchangeContactFolder)
 }
 
-func (suite *ExchangeSourceSuite) TestExchangeSelector_ExcludeEvents() {
+func (suite *ExchangeSourceSuite) TestExchangeSelector_Exclude_Events() {
 	t := suite.T()
 	sel := NewExchangeBackup()
 
@@ -150,7 +150,7 @@ func (suite *ExchangeSourceSuite) TestExchangeSelector_ExcludeEvents() {
 		e2   = "e2"
 	)
 
-	sel.ExcludeEvents(user, e1, e2)
+	sel.Exclude(sel.Events(user, e1, e2))
 	scopes := sel.Excludes
 	require.Equal(t, 1, len(scopes))
 
@@ -159,7 +159,7 @@ func (suite *ExchangeSourceSuite) TestExchangeSelector_ExcludeEvents() {
 	assert.Equal(t, scope[ExchangeEvent.String()], join(e1, e2))
 }
 
-func (suite *ExchangeSourceSuite) TestExchangeSelector_IncludeEvents() {
+func (suite *ExchangeSourceSuite) TestExchangeSelector_Include_Events() {
 	t := suite.T()
 	sel := NewExchangeBackup()
 
@@ -169,7 +169,7 @@ func (suite *ExchangeSourceSuite) TestExchangeSelector_IncludeEvents() {
 		e2   = "e2"
 	)
 
-	sel.IncludeEvents(user, e1, e2)
+	sel.Include(sel.Events(user, e1, e2))
 	scopes := sel.Includes
 	require.Equal(t, 1, len(scopes))
 
@@ -180,7 +180,7 @@ func (suite *ExchangeSourceSuite) TestExchangeSelector_IncludeEvents() {
 	assert.Equal(t, sel.Scopes()[0].Category(), ExchangeEvent)
 }
 
-func (suite *ExchangeSourceSuite) TestExchangeSelector_ExcludeMail() {
+func (suite *ExchangeSourceSuite) TestExchangeSelector_Exclude_Mails() {
 	t := suite.T()
 	sel := NewExchangeBackup()
 
@@ -191,7 +191,7 @@ func (suite *ExchangeSourceSuite) TestExchangeSelector_ExcludeMail() {
 		m2     = "m2"
 	)
 
-	sel.ExcludeMail(user, folder, m1, m2)
+	sel.Exclude(sel.Mails(user, folder, m1, m2))
 	scopes := sel.Excludes
 	require.Equal(t, 1, len(scopes))
 
@@ -201,7 +201,7 @@ func (suite *ExchangeSourceSuite) TestExchangeSelector_ExcludeMail() {
 	assert.Equal(t, scope[ExchangeMail.String()], join(m1, m2))
 }
 
-func (suite *ExchangeSourceSuite) TestExchangeSelector_IncludeMail() {
+func (suite *ExchangeSourceSuite) TestExchangeSelector_Include_Mails() {
 	t := suite.T()
 	sel := NewExchangeBackup()
 
@@ -212,7 +212,7 @@ func (suite *ExchangeSourceSuite) TestExchangeSelector_IncludeMail() {
 		m2     = "m2"
 	)
 
-	sel.IncludeMail(user, folder, m1, m2)
+	sel.Include(sel.Mails(user, folder, m1, m2))
 	scopes := sel.Includes
 	require.Equal(t, 1, len(scopes))
 
@@ -224,7 +224,7 @@ func (suite *ExchangeSourceSuite) TestExchangeSelector_IncludeMail() {
 	assert.Equal(t, sel.Scopes()[0].Category(), ExchangeMail)
 }
 
-func (suite *ExchangeSourceSuite) TestExchangeSelector_ExcludeMailFolders() {
+func (suite *ExchangeSourceSuite) TestExchangeSelector_Exclude_MailFolders() {
 	t := suite.T()
 	sel := NewExchangeBackup()
 
@@ -234,7 +234,7 @@ func (suite *ExchangeSourceSuite) TestExchangeSelector_ExcludeMailFolders() {
 		f2   = "f2"
 	)
 
-	sel.ExcludeMailFolders(user, f1, f2)
+	sel.Exclude(sel.MailFolders(user, f1, f2))
 	scopes := sel.Excludes
 	require.Equal(t, 1, len(scopes))
 
@@ -244,7 +244,7 @@ func (suite *ExchangeSourceSuite) TestExchangeSelector_ExcludeMailFolders() {
 	assert.Equal(t, scope[ExchangeMail.String()], None)
 }
 
-func (suite *ExchangeSourceSuite) TestExchangeSelector_IncludeMailFolders() {
+func (suite *ExchangeSourceSuite) TestExchangeSelector_Include_MailFolders() {
 	t := suite.T()
 	sel := NewExchangeBackup()
 
@@ -254,7 +254,7 @@ func (suite *ExchangeSourceSuite) TestExchangeSelector_IncludeMailFolders() {
 		f2   = "f2"
 	)
 
-	sel.IncludeMailFolders(user, f1, f2)
+	sel.Include(sel.MailFolders(user, f1, f2))
 	scopes := sel.Includes
 	require.Equal(t, 1, len(scopes))
 
@@ -266,7 +266,7 @@ func (suite *ExchangeSourceSuite) TestExchangeSelector_IncludeMailFolders() {
 	assert.Equal(t, sel.Scopes()[0].Category(), ExchangeMailFolder)
 }
 
-func (suite *ExchangeSourceSuite) TestExchangeSelector_ExcludeUsers() {
+func (suite *ExchangeSourceSuite) TestExchangeSelector_Exclude_Users() {
 	t := suite.T()
 	sel := NewExchangeBackup()
 
@@ -275,7 +275,7 @@ func (suite *ExchangeSourceSuite) TestExchangeSelector_ExcludeUsers() {
 		u2 = "u2"
 	)
 
-	sel.ExcludeUsers(u1, u2)
+	sel.Exclude(sel.Users(u1, u2))
 	scopes := sel.Excludes
 	require.Equal(t, 1, len(scopes))
 
@@ -288,7 +288,7 @@ func (suite *ExchangeSourceSuite) TestExchangeSelector_ExcludeUsers() {
 	assert.Equal(t, scope[ExchangeMailFolder.String()], None)
 }
 
-func (suite *ExchangeSourceSuite) TestExchangeSelector_IncludeUsers() {
+func (suite *ExchangeSourceSuite) TestExchangeSelector_Include_Users() {
 	t := suite.T()
 	sel := NewExchangeBackup()
 
@@ -297,7 +297,7 @@ func (suite *ExchangeSourceSuite) TestExchangeSelector_IncludeUsers() {
 		u2 = "u2"
 	)
 
-	sel.IncludeUsers(u1, u2)
+	sel.Include(sel.Users(u1, u2))
 	scopes := sel.Includes
 	require.Equal(t, 1, len(scopes))
 

src/pkg/selectors/selectors.go

@@ -18,6 +18,12 @@ var ErrorBadSelectorCast = errors.New("wrong selector service type")
 
 const (
 	scopeKeyCategory    = "category"
+	scopeKeyGranularity = "granularity"
+)
+
+const (
+	Group = "group"
+	Item  = "item"
 )
 
 const (