github.com/cornelk/go-cloud@v0.17.1/docstore/urls.go (about)

     1  // Copyright 2019 The Go Cloud Development Kit Authors
     2  //
     3  // Licensed under the Apache License, Version 2.0 (the "License");
     4  // you may not use this file except in compliance with the License.
     5  // You may obtain a copy of the License at
     6  //
     7  //     https://www.apache.org/licenses/LICENSE-2.0
     8  //
     9  // Unless required by applicable law or agreed to in writing, software
    10  // distributed under the License is distributed on an "AS IS" BASIS,
    11  // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    12  // See the License for the specific language governing permissions and
    13  // limitations under the License.
    14  
    15  package docstore
    16  
    17  import (
    18  	"context"
    19  	"net/url"
    20  
    21  	"github.com/cornelk/go-cloud/internal/openurl"
    22  )
    23  
    24  // CollectionURLOpener opens a collection of documents based on a URL.
    25  // The opener must not modify the URL argument. It must be safe to call from
    26  // multiple goroutines.
    27  //
    28  // This interface is generally implemented by types in driver packages.
    29  type CollectionURLOpener interface {
    30  	OpenCollectionURL(ctx context.Context, u *url.URL) (*Collection, error)
    31  }
    32  
    33  // URLMux is a URL opener multiplexer. It matches the scheme of the URLs against
    34  // a set of registered schemes and calls the opener that matches the URL's
    35  // scheme. See https://github.com/cornelk/go-cloud/concepts/urls/ for more information.
    36  //
    37  // The zero value is a multiplexer with no registered scheme.
    38  type URLMux struct {
    39  	schemes openurl.SchemeMap
    40  }
    41  
    42  // CollectionSchemes returns a sorted slice of the registered Collection schemes.
    43  func (mux *URLMux) CollectionSchemes() []string { return mux.schemes.Schemes() }
    44  
    45  // ValidCollectionScheme returns true iff scheme has been registered for Collections.
    46  func (mux *URLMux) ValidCollectionScheme(scheme string) bool { return mux.schemes.ValidScheme(scheme) }
    47  
    48  // RegisterCollection registers the opener with the given scheme. If an opener
    49  // already exists for the scheme, RegisterCollection panics.
    50  func (mux *URLMux) RegisterCollection(scheme string, opener CollectionURLOpener) {
    51  	mux.schemes.Register("docstore", "Collection", scheme, opener)
    52  }
    53  
    54  // OpenCollection calls OpenCollectionURL with the URL parsed from urlstr.
    55  // OpenCollection is safe to call from multiple goroutines.
    56  func (mux *URLMux) OpenCollection(ctx context.Context, urlstr string) (*Collection, error) {
    57  	opener, u, err := mux.schemes.FromString("Collection", urlstr)
    58  	if err != nil {
    59  		return nil, err
    60  	}
    61  	return opener.(CollectionURLOpener).OpenCollectionURL(ctx, u)
    62  }
    63  
    64  // OpenCollectionURL dispatches the URL to the opener that is registered with
    65  // the URL's scheme. OpenCollectionURL is safe to call from multiple goroutines.
    66  func (mux *URLMux) OpenCollectionURL(ctx context.Context, u *url.URL) (*Collection, error) {
    67  	opener, err := mux.schemes.FromURL("Collection", u)
    68  	if err != nil {
    69  		return nil, err
    70  	}
    71  	return opener.(CollectionURLOpener).OpenCollectionURL(ctx, u)
    72  }
    73  
    74  var defaultURLMux = new(URLMux)
    75  
    76  // DefaultURLMux returns the URLMux used by OpenCollection.
    77  //
    78  // Driver packages can use this to register their CollectionURLOpener on the mux.
    79  func DefaultURLMux() *URLMux {
    80  	return defaultURLMux
    81  }
    82  
    83  // OpenCollection opens the collection identified by the URL given.
    84  // See the URLOpener documentation in driver subpackages for details
    85  // on supported URL formats, and https://github.com/cornelk/go-cloud/concepts/urls/ for more
    86  // information.
    87  func OpenCollection(ctx context.Context, urlstr string) (*Collection, error) {
    88  	return defaultURLMux.OpenCollection(ctx, urlstr)
    89  }